--- inclusion: manual --- # Monthly MBR Workflow — Playbook (Template) > **Purpose**: Automated Monthly Business Review workflow — Quick gathers engagement data, Kiro drafts STAR narratives and SIFT entries for Salesforce. > > **Audience**: Any Amazon SA, CSM, or TAM who runs monthly business reviews with SIFT Field Insights. > > **Time to set up**: ~20 minutes (Quick agent + Kiro hook). > > **Platform**: Works on both macOS and Windows. Path examples show both formats. > > **Version**: 1.2 · Last updated: 2026-04-24 **How to use this template:** Replace all `{{PLACEHOLDER}}` values with your own details. Search for `{{` to find every spot that needs customization. Once filled in, save this file to your Kiro project and it becomes your persistent MBR workflow reference. **⚠ Keep accounts in sync:** Your account list appears in two places — the [Key Accounts Reference](#key-accounts-reference) table and the [Quick agent prompt](#2-create-the-quick-scheduled-agent). When you add or remove accounts, update both. --- ## Overview Every second Monday, Quick gathers customer engagement data and drops a briefing file. Kiro picks it up (via hook or manual trigger), drafts STAR narratives, exports a `.docx`, and prepares SIFT entries for Salesforce. ``` ┌───────────────────────────────────────────────────────────────────────────┐ │ Amazon Quick (Scheduled Agent) │ │ ┌───────────┐ ┌──────────────┐ ┌─────────────────────────────┐ │ │ │ cron_like │───▶│ 2nd-monday │───▶│ Agent (LLM) │ │ │ │ Mon 08:30 │ │ check.py │ │ 1. Scan calendar (45 days) │ │ │ └───────────┘ │ gate=True? │ │ 2. Pull SFDC context │ │ │ └──────────────┘ │ 3. Score & prioritize │ │ │ │ 4. Write briefing file │ │ │ └──────────┬──────────────────┘ │ └──────────────────────────────────────────────────┼──────────────────────┘ │ ▼ ~/quick-kiro-handoff/ YYYY-MM-DD_monthly-mbr-prep_briefing.md │ ┌──────────────────────────────────────────────────┼──────────────────────┐ │ Kiro IDE (Hook or Manual Trigger) │ │ │ ┌──────────▼──────────────────┐ │ │ │ Kiro Workflow │ │ │ │ 1. Read briefing │ │ │ │ 2. Draft STAR narratives │ │ │ │ 3. ⏸ USER APPROVES │ │ │ │ 4. Export MBR .docx │ │ │ │ 5. Draft SIFT entries │ │ │ │ 6. ⏸ USER APPROVES (each) │ │ │ │ 7. Post to Salesforce │ │ │ └──────────┬──────────────────┘ │ └──────────────────────────────────────────────────┼──────────────────────┘ │ ┌────────────────┬───────────────────┼───────────────┐ ▼ ▼ ▼ ▼ ┌────────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Desktop .docx │ │ Handoff .md │ │ SFDC / SIFT │ │ Feed notify │ │ (MBR export) │ │ (archive) │ │ (insights) │ │ (summary) │ └────────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ``` --- ## Prerequisites Before setting up this workflow, ensure you have: 1. **Amazon Quick Desktop** installed and configured with: - Outlook integration (calendar access) — **required** - AWSentral MCP (Salesforce access) — **required** - Scheduled agents enabled - Quick will look up your **SFDC User ID** automatically via AWSentral during setup 2. **Kiro IDE** installed with the following MCP servers active: - **aws-sentral-mcp** — provides `sift_insights_create` for posting SIFT Field Insights to Salesforce - **aws-outlook-mcp** — Outlook calendar access for scanning meetings - **builder-mcp** — Builder Tools for internal resource access - **markitdown-mcp** — document conversion - **aws-knowledge-mcp-server-mcp** — AWS knowledge base access - **playwright-mcp** — browser automation (used for some SFDC lookups) > **How to install MCP servers:** If you've installed Kiro Powers, these are already configured. If not, add them manually in Kiro → Settings → MCP Servers. Each server needs its own configuration entry. Ask your team lead or the Kiro & Quick channel for config templates. > > **Note on hook syntax:** The Kiro hook format in this template is based on Kiro's current API. If you're using a different Kiro version, verify the hook syntax against Kiro's documentation. The manual trigger method works regardless of hook format. 3. **A handoff directory** — see [Setup Step 1](#1-create-the-handoff-directory) 4. **Your customer account names** — just the names (e.g., "Acme Corp"). Quick will resolve Account IDs automatically. See [Key Accounts Reference](#key-accounts-reference) for the template. > **Manual lookup (if needed):** Your SFDC User ID (starts with `005`) is in Salesforce: avatar → Settings → My Personal Information → User ID. Account IDs (start with `001`) are in each account's Salesforce URL. --- ## File Locations > **Windows users:** Wherever you see `~/`, substitute `%USERPROFILE%\` (CMD) or `$env:USERPROFILE\` (PowerShell). For example, `~/quick-kiro-handoff/` becomes `C:\Users\YourName\quick-kiro-handoff\`. Kiro and Quick both accept forward slashes on Windows, so paths like `~/quick-kiro-handoff/` will also work inside those tools. | What | Path | |------|------| | Kiro hook | `.kiro/hooks/monthly-mbr-workflow.kiro.hook` | | Handoff directory | `~/quick-kiro-handoff/` | | Briefing file (Quick writes) | `~/quick-kiro-handoff/YYYY-MM-DD_monthly-mbr-prep_briefing.md` | | MBR output (Desktop) | `~/Desktop/MBR_[Month]_[Year].docx` | | MBR output (handoff copy) | `~/quick-kiro-handoff/YYYY-MM-DD_kiro_mbr.md` | | Quick agent config | `.quickwork/agents.json` → `monthly-mbr-prep` | | Quick trigger script | `.quickwork/triggers/custom/second-monday-check.py` | --- ## Placeholders Reference | Placeholder | Description | Example | |-------------|-------------|---------| | `{{YOUR_SFDC_USER_ID}}` | Your Salesforce User ID (starts with `005`) | `005XXXXXXXXXXEXAMPLE` | | `{{CUSTOMER_N}}` | Customer account name | `Acme Corp` | | `{{ACCOUNT_ID_N}}` | SFDC Account ID (starts with `001`) | `001XXXXXXXXX` | | `{{EXPORT_PATH}}` | Where to save the MBR .docx | macOS: `~/Desktop` · Windows: `%USERPROFILE%\Desktop` | --- ## Setup ### 1. Create the handoff directory **macOS / Linux:** ```bash mkdir -p ~/quick-kiro-handoff ``` **Windows (PowerShell):** ```powershell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\quick-kiro-handoff" ``` ### 2. Create the Quick scheduled agent In Amazon Quick Desktop, create a scheduled agent named `monthly-mbr-prep` with: - **Schedule:** `cron_like` — 08:30 on Mondays, days: `[mon]` - **Condition gate:** Second Monday of the month only (use the trigger script in step 3) - **Model:** `thinking` (recommended for complex data gathering) - **Resilience:** If unable to execute at the scheduled time, execute when next able to #### Tool Policy ```json [ { "group": "outlook_mcp", "effect": "allow" }, { "group": "user_mcp__aws_sentral_mcp", "effect": "allow" }, { "group": "core", "effect": "allow" }, { "tool": "file_write", "effect": "allow", "conditions": [{ "mode": "regex", "argument": "path", "pattern": ".*quick-kiro-handoff.*\\.md$" }] } ] ``` | Group/Tool | Access | Purpose | |------------|--------|---------| | `outlook_mcp` | Read | Search calendar for meetings | | `user_mcp__aws_sentral_mcp` | Read | Search opportunities, accounts, tech activities | | `core` | Read | Time, file operations | | `file_write` | Write (scoped) | Save briefing file to handoff directory | #### Agent Prompt Use the following as the agent's **objective/prompt** (replace all `{{...}}` values): ``` You are the Monthly MBR Prep agent. Your job is to scan recent customer engagements and produce a structured briefing file for Kiro to consume downstream. ## Identity - SFDC User ID: {{YOUR_SFDC_USER_ID}} ## CRITICAL RULES - Do NOT use run_python to parse JSON tool responses — use the tool results directly (run_python cannot access MCP tool response objects; parsing them causes silent failures) - Do NOT create any SIFT entries or MBR documents. Your ONLY job is to produce the briefing file. Kiro handles everything downstream. - ALWAYS use the target month dates from the condition gate. Do NOT assume the current calendar month is the scan target. ## Accounts to scan {{CUSTOMER_1}} — {{ACCOUNT_ID_1}} {{CUSTOMER_2}} — {{ACCOUNT_ID_2}} {{CUSTOMER_3}} — {{ACCOUNT_ID_3}} {{CUSTOMER_4}} — {{ACCOUNT_ID_4}} {{CUSTOMER_5}} — {{ACCOUNT_ID_5}} ## Scoring Criteria Rank engagements by impact using these factors (weighted): 1. **Pipeline impact** (highest weight) — did this advance an opportunity stage, increase ARR, or unblock a deal? 2. **Strategic importance** — is this a flagship account, a new logo, or a competitive displacement? 3. **Technical depth** — was this a deep architecture review, PoC, or workshop (vs. a status call)? 4. **Customer escalation** — did this involve a critical issue, risk mitigation, or executive engagement? 5. **New service adoption** — did the customer adopt or evaluate a new AWS service? ## Instructions 1. Determine the target date range from the condition gate (target_month/target_year). Calculate first_of_month and last_of_month. Scan from ~45 days before last_of_month to last_of_month. 2. Call calendar_view to retrieve ALL meetings for the date range. Filter client-side for meetings involving the accounts above (match by title, attendee domains, description). 3. For each account with meaningful engagement, pull SFDC context: - Account summary, open opportunities (ID, name, stage, ARR), recent tech activities 4. If search_opportunities returns zero results for an account, note it but still include calendar engagements — use the Account ID as context. 5. Score and prioritize — pick the top 5 most impactful engagements using the Scoring Criteria above. 6. Write the output to: ~/quick-kiro-handoff/YYYY-MM-DD_monthly-mbr-prep_briefing.md using this format: # Monthly MBR Prep Briefing Date: YYYY-MM-DD Period: [start date] to [end date] ## Engagement 1: [Customer Name] - Account ID: [SFDC account ID] - Impact Score: [1-5, with brief justification] - Meetings: [dates, attendees, format (virtual/in-person)] - Opportunities: [opp ID, name, stage, ARR] - Context: [what happened, why it matters] - Services: [AWS services discussed/used] ## Engagement 2: ... 7. Call update_feed with importance="important" summarizing what was written. ``` ### 3. Create the trigger script Save this to `.quickwork/triggers/custom/second-monday-check.py`: ```python def check(params, tools, state): """ Returns truthy dict only on the second Monday of the current month. The agent's cron_like schedule already ensures this runs on Mondays, so we only need to verify it's the SECOND Monday. Returns target date range for the briefing scan period. """ from datetime import date, timedelta import calendar today = date.today() # Check if this is the second Monday: day falls between 8-14 if today.weekday() != 0: # Monday = 0 return False week_of_month = (today.day - 1) // 7 + 1 if week_of_month != 2: return False # Calculate scan range: ~45 days back from end of current month last_day = calendar.monthrange(today.year, today.month)[1] end_date = today.replace(day=last_day) start_date = end_date - timedelta(days=45) return { "second_monday": str(today), "month": today.strftime("%B %Y"), "target_year": today.year, "target_month": today.month, "scan_start": str(start_date), "scan_end": str(end_date), "first_of_month": str(today.replace(day=1)), "last_of_month": str(end_date) } ``` ### 4. Create the Kiro hook Save this to `.kiro/hooks/monthly-mbr-workflow.kiro.hook`: > **Note:** Hook syntax may vary by Kiro version. If this hook doesn't fire, use the [Manual Trigger](#manual-trigger) method instead. ```yaml # Monthly MBR Workflow Hook # Triggers when Quick drops a briefing file into the handoff directory. # Kiro will automatically start the MBR workflow (STAR narratives → doc export → SIFT entries). # # To create this file: # 1. In your Kiro project, create the directory: .kiro/hooks/ # macOS/Linux: mkdir -p .kiro/hooks # Windows: mkdir .kiro\hooks # 2. Save this file as: monthly-mbr-workflow.kiro.hook # 3. Restart Kiro to pick up the new hook: # macOS: Cmd+Shift+P → "Reload Window" # Windows: Ctrl+Shift+P → "Reload Window" event: fileCreated pattern: "**/quick-kiro-handoff/*mbr-prep*briefing*.md" action: run-workflow ``` --- ## Manual Trigger If the hook didn't fire, or you want to run the workflow on demand: 1. Check for a briefing file: **macOS / Linux:** ``` ls ~/quick-kiro-handoff/*mbr-prep*briefing*.md ``` **Windows (PowerShell):** ```powershell Get-ChildItem "$env:USERPROFILE\quick-kiro-handoff\*mbr-prep*briefing*.md" ``` 2. If one exists, tell Kiro: > "Read the MBR briefing in ~/quick-kiro-handoff/ and run the full MBR workflow" 3. If no briefing exists, you can create one manually (see [Briefing File Format](#briefing-file-format) below) or tell Kiro: > "Run my MBR briefing" — Kiro will scan calendar and SFDC directly --- ## Step-by-Step Workflow (Kiro) > **Note:** Steps 1–5 below are instructions for **Kiro** to follow when executing the MBR workflow. ### Step 1 — Read the briefing Read the handoff file from `~/quick-kiro-handoff/`. It contains up to 5 customer engagements from the last 45 days, each with: - Customer name and account ID - Impact score and justification - Meeting dates and attendees - Open opportunities (ID, stage, ARR) - Engagement context and notes If the briefing contains fewer than 5 engagements, proceed with what's available. If an account ID is missing for an engagement, flag it to the user and skip SIFT entry creation for that engagement. ### Step 2 — Draft STAR narratives For each engagement, write a narrative in STAR format: - **Situation** — customer context, business challenge, why this engagement happened - **Task** — what the SA/CSM needed to accomplish - **Action** — specific technical work done (demos, architecture reviews, workshops, etc.) - **Result** — outcomes, next steps, pipeline impact, customer sentiment Present all drafts to the user at once. Wait for explicit approval before proceeding. ### Step 3 — Export MBR document After narrative approval, immediately (no confirmation needed): 1. Write `{{EXPORT_PATH}}/MBR_[Month]_[Year].docx` with all approved narratives 2. Write `~/quick-kiro-handoff/YYYY-MM-DD_kiro_mbr.md` as a markdown archive copy 3. Confirm both files were saved > **Note on format:** Use `.docx` (not `.doc`). Kiro can generate `.docx` via its document conversion tools. The legacy `.doc` format (Word 97-2003) is not supported. ### Step 4 — Draft SIFT entries For each engagement, draft a SIFT Field Insight with: - **title** — concise, specific (customer name + what happened + why it matters) - **description** — detailed narrative (2–4 paragraphs) - **summary** — 1–2 sentence version - **category** — one of the values in the SIFT Category Reference below - **accountIds** — SFDC account ID from the briefing - **opportunityIds** — SFDC opportunity IDs if applicable - **services** — AWS services involved (see [SIFT Field Reference](#sift-field-reference) below) - **domains** — technical domains - **industries** — customer industry - **segments** — market segment - **geos** — geographic region Present all SIFT drafts for review. Do NOT create anything in Salesforce yet. ### Step 5 — Post SIFT entries to Salesforce After the user explicitly approves each entry, create it using `sift_insights_create` (provided by the `aws-sentral-mcp` MCP server). Post one at a time, confirming each result. > **If `sift_insights_create` is not available:** Check that your `aws-sentral-mcp` server is running in Kiro (Settings → MCP Servers). You may need to restart Kiro after enabling it. After all SIFT entries are posted, summarize what was created (customer, category, status) and confirm the MBR workflow is complete. --- ## SIFT Field Reference Use these exact enum values when creating SIFT entries. If unsure about a value, run `sift_insights_create` with no args to see the full list of valid options for your org. ### Categories | Value | Use when | |-------|----------| | `Highlight` | Positive outcome — deal progress, successful engagement, customer win | | `Lowlight` | Negative outcome — lost deal, failed PoC, customer churn risk | | `Risk` | Potential future problem — timeline risk, competitive threat, budget concern | | `Observation` | Neutral insight — market trend, customer strategy shift, org change | | `Blocker` | Active impediment — service limitation, support gap, process issue | | `Challenge` | Ongoing difficulty — adoption barrier, skill gap, integration complexity | | `Health of the Business` | Overall account health assessment | ### Common Services | Keywords in engagement | Service value | |------------------------|---------------| | bedrock, foundation model, RAG | `Amazon Bedrock` | | sagemaker, ML | `Amazon SageMaker` | | lambda, serverless | `AWS Lambda` | | ECS, EKS, container | `Amazon ECS` or `Amazon EKS` | | connect, contact center | `Amazon Connect` | | redshift, data warehouse | `Amazon Redshift` | | S3, storage | `Amazon S3` | | DynamoDB | `Amazon DynamoDB` | > **Important:** Service enum values must match exactly what `sift_insights_create` expects. Run the tool with no args to get the authoritative list for your org. ### Common Domains `GenAI`, `Machine Learning`, `Serverless`, `Containers`, `Analytics`, `Database`, `Storage`, `Migration & Modernization`, `Security`, `Networking` ### Common Segments `SUP` (Startup), `SMB` (Small/Medium Business), `ENT` (Enterprise), `ISV`, `PS` (Public Sector) ### Common Geos `NAMER` (North America), `EMEA`, `APJ` (Asia Pacific & Japan), `LATAM` ### Common Industries `Automotive`, `Education`, `Energy`, `Financial Services`, `Games`, `Government`, `Healthcare`, `Manufacturing`, `Media & Entertainment`, `Retail`, `Software & Internet`, `Telecommunications`, `Travel & Hospitality` --- ## Approval Gates | Action | Requires approval? | |--------|---------------------| | Draft STAR narratives | No (drafting is automatic) | | Approve narratives before export | **Yes** | | Export MBR .docx to Desktop | No (automatic after narrative approval) | | Draft SIFT entries | No (drafting is automatic) | | Post SIFT to Salesforce | **Yes — per entry** | --- ## Briefing File Format If creating a briefing manually (or if the Quick agent needs a reference), use this structure: ```markdown # Monthly MBR Prep Briefing Date: YYYY-MM-DD Period: [start date] to [end date] ## Engagement 1: [Customer Name] - Account ID: [SFDC account ID] - Impact Score: [1-5, with brief justification] - Meetings: [dates, attendees, format] - Opportunities: [opp ID, name, stage, ARR] - Context: [what happened, why it matters] - Services: [AWS services discussed/used] ## Engagement 2: [Customer Name] ... ``` --- ## Key Accounts Reference > **Customize this table** with your own customers and their SFDC Account IDs. You can find Account IDs in Salesforce: navigate to the account page — the 18-character ID is in the URL (e.g., `https://aws-crm.lightning.force.com/lightning/r/Account/001XXXXXXXXX/view` → Account ID is `001XXXXXXXXX`). | Customer | Account ID | Industry | |----------|------------|----------| | `{{CUSTOMER_1}}` | `{{ACCOUNT_ID_1}}` | `{{INDUSTRY_1}}` | | `{{CUSTOMER_2}}` | `{{ACCOUNT_ID_2}}` | `{{INDUSTRY_2}}` | | `{{CUSTOMER_3}}` | `{{ACCOUNT_ID_3}}` | `{{INDUSTRY_3}}` | | `{{CUSTOMER_4}}` | `{{ACCOUNT_ID_4}}` | `{{INDUSTRY_4}}` | | `{{CUSTOMER_5}}` | `{{ACCOUNT_ID_5}}` | `{{INDUSTRY_5}}` | Add or remove rows as needed. --- ## Customization Options | What | How | |------|-----| | **Change cadence** | Modify the trigger script — change `week_of_month != 2` to `!= 1` for first Monday, `!= 3` for third, etc. | | **Engagement window** | Adjust the `timedelta(days=45)` in the trigger and the "~45 days" in the prompt | | **Max engagements** | Change "top 5" in the Quick agent prompt | | **Export path** | Change `{{EXPORT_PATH}}` in Step 3 | | **Add/remove accounts** | Update BOTH the Key Accounts table AND the agent prompt | | **Skip SIFT entirely** | Remove Steps 4-5 from the Kiro workflow | | **Run without Quick** | Skip the agent setup; tell Kiro directly: "Run my MBR briefing" — it will scan calendar/SFDC itself | | **Run without Kiro** | Use Quick's briefing file as your MBR source and create SIFT entries manually | --- ## Resuming Pending Work If a previous session drafted SIFT entries but didn't post them, check `~/quick-kiro-handoff/` for a `kiro_mbr` file from the relevant date. It will contain the narratives. Then tell Kiro: > "Create the SIFT entries from my [Month] MBR — [list customers and categories]" Example: > "Create the three SIFT entries from my April MBR — Acme Corp Highlight, Beta Inc Highlight, and Gamma LLC Observation" --- ## FAQ **Q: What roles does this work for?** A: Any SA, CSM, TAM, or customer-facing role that writes MBR narratives and/or posts SIFT Field Insights. **Q: Do I need both Quick and Kiro?** A: No. Quick automates the data gathering; Kiro automates the narrative drafting and SIFT posting. You can use either independently — see [Customization Options](#customization-options). **Q: What if Quick found no engagements this month?** A: The briefing file will be empty or minimal. Kiro will note there's nothing to draft and ask if you want to proceed with manual input. **Q: Can I change the cadence to weekly or quarterly?** A: Yes. Modify the trigger script for your desired frequency (see [Customization Options](#customization-options)). **Q: What if I cover accounts in multiple industries/geos?** A: Set the industry and geo per account in the Key Accounts table. The SIFT entries use per-account values. **Q: The SIFT entry failed with an invalid service value. What do I do?** A: The service enum must match exactly. Run `sift_insights_create` with no args to get the valid list for your org. Update the [SIFT Field Reference](#sift-field-reference) with correct values. **Q: Can I run this mid-cycle?** A: Yes — trigger the Quick agent manually (the condition gate only applies to automated runs), or tell Kiro directly to scan and draft. --- ## Troubleshooting | Issue | Fix | |-------|-----| | Hook didn't fire | Check that the briefing filename matches the glob pattern. Ensure `.kiro/hooks/` directory exists and Kiro was restarted. Use the [Manual Trigger](#manual-trigger) method. | | Quick agent didn't run | Verify the agent is enabled. Check the trigger: `python3 .quickwork/triggers/custom/second-monday-check.py`. Ensure it returns a dict on the correct Monday. | | `sift_insights_create` not found | Ensure `aws-sentral-mcp` is listed and active in Kiro → Settings → MCP Servers. Restart Kiro after enabling. | | SIFT creation fails | Verify Account IDs are valid in SFDC. Check that field values (services, domains, etc.) match the exact enums — see [SIFT Field Reference](#sift-field-reference). | | No calendar data | Confirm Outlook integration is active in Quick. Check Midway auth is current (`mwinit`). | | No SFDC data | Confirm AWSentral MCP is active. Re-authenticate if needed. Verify your SFDC User ID is correct. | | Hook file not recognized | Ensure the file is saved with the `.kiro.hook` extension (not `.hook.txt`). Check that it's in the `.kiro/hooks/` directory at the root of your Kiro project. | | Agent found zero engagements | Verify account names in the prompt match calendar meeting titles. Add email domain searches for better matching. | | .docx export fails in Kiro | Ensure `markitdown-mcp` is active. Verify Kiro has write access to `{{EXPORT_PATH}}`. | --- *Reusable MBR workflow template for Amazon Quick + Kiro. Contributions welcome — extend the SIFT field tables for your org and share back.*