# BeaconIQ — Setup Guide (v3)

> **Targeted AWS Announcement Intelligence for Account Teams**
> Works on Mac and Windows | Requires Amazon Quick Desktop + Kiro IDE

---

## What Is BeaconIQ?

BeaconIQ is a personal intelligence system that scans internal sources for new AWS product launches, feature releases, and partner announcements — then cross-references them against **your specific customer portfolio** to surface only the most relevant, actionable recommendations.

⏱️ **Setup time: ~15 minutes.** Just copy-paste the prompts below into Quick and Kiro — they build everything for you.

**What it delivers:**
- A weekly **Excel digest** on your Desktop with prescriptive guidance like *"Customer X runs Aurora PostgreSQL with 3 read replicas — new Aurora Limitless could reduce their read latency by 40%. Recommend adding to next QBR."*
- An **executive brief** with PFR resolutions and competitive positioning summaries
- **Real-time PFR alerts** when a new release matches a customer's open Product Feature Request
- **Portfolio-level insights** when the same announcement matters to multiple customers in your vertical

**Who it's for:** Account Managers, Customer Solutions Managers, Solutions Architects — anyone managing AWS customer accounts.

**What it requires:** Your corporate laptop + Amazon Quick Desktop + Kiro IDE. No cloud infrastructure. No deployments. Everything runs locally.

### v3 Features

- 🚨 **PFR Resolution Alerts** — instant notification when a new release matches a customer's open PFR. Highest-priority signal — CSM should call within days.
- 🏁 **Competitive Intelligence** — battle cards and positioning talk tracks when competitors are involved
- 📊 **Portfolio Patterns** — flags when 3+ customers in the same vertical match an announcement, with portfolio-level actions
- 📝 **Executive Brief** — PFR resolutions + competitive positioning summary delivered alongside the digest
- 📈 **Outcome Tracking** — log customer reactions after discussions; BeaconIQ learns and improves future scoring
- 👁️ **Watch List** — tracks preview/beta services your customers use; pre-scopes research so GA drops are processed faster
- 📋 **QBR Integration** — 90-day recommendation history for auto-generating "What's New" slides per customer

---

## How It Works

BeaconIQ uses two AI agents that collaborate through a shared folder on your laptop:

```
Friday 3:00 PM     Quick scans Slack, email, AWSentral
                    → scores relevance (incl. PFR + competitor matching)
                    → drops research signals for Kiro
                    → sends immediate alert for PFR matches
                            ↓
Friday PM – Mon AM  Kiro browses Highspot, wikis, Partner Central
                    → PFR signals processed FIRST
                    → competitive battle cards pulled
                    → writes enrichment files
                            ↓
Monday 10:00 AM     Quick merges everything
                    → generates consolidated Excel digest + executive brief
                    → detects portfolio patterns across customers
                    → saves to Desktop + emails to you
```

| Agent | Role | Sources |
|---|---|---|
| **Amazon Quick** | Always-on runtime — scans, scores, delivers | Slack, Outlook, AWSentral/SIFT, local files |
| **Kiro IDE** | Deep researcher — browses web-based tools, logs outcomes | Highspot, internal wikis, Partner Central |

---

## Prerequisites

### Required

- [ ] **Amazon Quick Desktop** — installed and signed in
  - Slack connected (Settings → Integrations)
  - Outlook connected (Settings → Integrations)
  - AWSentral MCP configured (see [AWSentral MCP Setup](#awsentral-mcp-setup) below)

- [ ] **Kiro IDE** — installed and signed in
  - Playwright MCP configured (for browsing internal sites)

### Recommended

- [ ] At least one local folder with customer architecture docs or account plans added to Quick (Settings → Capabilities → Folders)
- [ ] Midway authenticated (`mwinit` session active)

---

## Step 1: Create the Handoff Folder

Quick and Kiro communicate through a shared folder. Create it:

**Mac:**
```bash
mkdir -p ~/quick-kiro-handoff
```

**Windows (PowerShell):**
```powershell
New-Item -ItemType Directory -Path "$env:USERPROFILE\quick-kiro-handoff" -Force
```

Then add this folder to Amazon Quick:
1. Open Quick → Settings (gear icon, bottom-left)
2. Capabilities → Folders → Add Folder
3. Navigate to `quick-kiro-handoff` and select it

---

## Step 2: Install the BeaconIQ Skill in Quick

Open Amazon Quick and paste this message:

> I'd like to set up BeaconIQ v3. Please create a skill called `beaconiq` with the following workflow:
>
> **Trigger:** "what's new for my accounts" (also: "beaconiq", "run beaconiq", "beaconiq digest")
>
> **Workflow:**
> 1. On first run, ask me which Slack channels to monitor for AWS announcements and whether to use my full AWSentral portfolio or specific accounts. Remember my answers for future runs.
> 2. Search configured Slack channels for new announcements (keywords: "now available", "general availability", "new feature", "launch", "release", "what's new") within the last 7 days.
> 3. Search Outlook inbox for product/feature announcement emails within the last 7 days. Use LLM filtering to remove noise.
> 4. Check `~/quick-kiro-handoff/` for Kiro files: enrichments (`*_kiro_beaconiq-enrichment.md`), enrichment amendments (`*_kiro_beaconiq-enrichment-amendment.md`), outcome files (`*_kiro_beaconiq-outcome.md`), and feedback files (`*_kiro_beaconiq-feedback.md`). Merge enrichments, apply amendments, ingest outcomes into the knowledge graph for scoring refinement (interested → boost, not relevant → reduce), and apply feedback corrections.
> 5. Pull my customer portfolio from AWSentral — accounts, opportunities (including `primaryCompetitor`), tech activities, SIFT insights, and open PFRs. Write a customer context cache to `~/quick-kiro-handoff/beaconiq-customer-context-cache.md`.
> 6. Read `~/quick-kiro-handoff/beaconiq-watch-list.md` for preview services to watch. When a GA announcement matches a watch list item, tag the research signal with `depth: light`. Add any new preview/beta announcements to the watch list.
> 7. Search my local connected folders for customer architecture docs and account plans.
> 8. For each announcement × each customer, score relevance with these levels:
>    - **Critical** — announcement matches an open PFR. Send immediate notification. Tag signal with `PFR Match: true`, PFR ID/title, and `priority: critical`.
>    - **High** — direct match to customer service + known requirement.
>    - **Medium** — related service area or adjacent capability.
>    Include rationale, prescriptive guidance, competitor context (if applicable from AWSentral opportunities), and suggested action.
> 9. For High/Critical items needing deeper context, write research request signals to `~/quick-kiro-handoff/` using v3 format: Research Depth (deep/light/verify), Dedup ID, PFR fields, and Competitor Context section.
> 10. Generate an Excel digest with 4 sheets: Summary, Recommendations (by customer, Critical=red, High=green, Medium=amber), Portfolio Patterns (same announcement matching 3+ customers in a vertical), and Announcements (raw list). Also generate an executive brief (`BeaconIQ_Brief_YYYY-MM-DD.md`) with PFR Resolutions and Competitive Positioning sections.
> 11. Write `beaconiq-recommendation-history.json` to `~/quick-kiro-handoff/` with the last 90 days of recommendations for QBR generation.
> 12. Track recommendation funnel metrics in the knowledge graph (Surfaced → Enriched → Discussed → Actioned → Impact). Generate a quarterly effectiveness report.
> 13. Email the digest to me.
>
> Please save this as a reusable skill.

Quick will create and save the skill. Test it by saying: **"What's new for my accounts?"**

---

## Step 3: Create the Scheduled Agents in Quick

You need two scheduled agents — a scanner (Friday) and a consolidator (Monday).

### Agent 1: BeaconIQ Scanner (Friday 3 PM)

Paste this into Quick:

> Create a scheduled agent called `beaconiq-digest` that runs every **Friday at 3:00 PM**. It should:
>
> 1. Run the beaconiq skill's scan workflow — search Slack, email, load AWSentral portfolio (including open PFRs and competitor data from opportunities), read local docs
> 2. Check for Kiro outcome files (`*_kiro_beaconiq-outcome.md`) and feedback files (`*_kiro_beaconiq-feedback.md`) — ingest into knowledge graph for scoring adjustments
> 3. Read `~/quick-kiro-handoff/beaconiq-watch-list.md` — cross-reference GA announcements against watch list items. Tag matches with `depth: light`. Add new preview announcements to the watch list.
> 4. Score relevance including PFR cross-referencing. If an announcement matches an open customer PFR, tag as `priority: critical` with `PFR Match: true` and send an immediate notification
> 5. Save all intermediate results to `~/Desktop/BeaconIQ_Pass1_YYYY-MM-DD.json`
> 6. Write Kiro research request signals using v3 format: Research Depth (deep/light/verify), Dedup ID (kebab-case), PFR Match fields, and Competitor Context section where applicable
> 7. Write customer context cache to `~/quick-kiro-handoff/beaconiq-customer-context-cache.md`
> 8. Notify me that Pass 1 is complete. If PFR matches were found, highlight them in the notification.
> 9. Do NOT generate the final digest — that's Pass 2's job
>
> Give it access to: Slack (read), Outlook (read), AWSentral MCP, and file tools. Use the smart model. If it misses its scheduled time, run when next able.

### Agent 2: BeaconIQ Consolidator (Monday 10 AM)

Paste this into Quick:

> Create a scheduled agent called `beaconiq-consolidate` that runs every **Monday at 10:00 AM**. It should:
>
> 1. Read the Pass 1 results from `~/Desktop/BeaconIQ_Pass1_YYYY-MM-DD.json` (most recent Friday's file)
> 2. Read Kiro enrichment files (`*_kiro_beaconiq-enrichment.md`) AND enrichment amendments (`*_kiro_beaconiq-enrichment-amendment.md`) — apply amendments as corrections to enrichments
> 3. Merge Quick's findings + Kiro's enrichments into consolidated recommendations. If enrichments reference SIFT insight IDs, note them in the digest with 📝.
> 4. Detect portfolio patterns: if the same announcement matches 3+ customers in a vertical, flag it as a portfolio-level pattern
> 5. Generate an Excel workbook: `~/Desktop/BeaconIQ_Digest_YYYY-MM-DD.xlsx` with 4 sheets: Summary, Recommendations (by customer, Critical=red, High=green, Medium=amber), Portfolio Patterns (vertical trends + portfolio-level actions), and Announcements (raw list)
> 6. Generate an executive brief: `~/Desktop/BeaconIQ_Brief_YYYY-MM-DD.md` with: top recommendations summary, ⚡ PFR Resolutions This Week table (Customer, PFR, Announcement, Action Needed), and 🏁 Competitive Positioning Updates table (Customer, Competitor, Announcement, Your Advantage)
> 7. Write `beaconiq-recommendation-history.json` to `~/quick-kiro-handoff/` with the last 90 days of recommendations (for Kiro's QBR generation)
> 8. Track recommendation funnel in knowledge graph: Surfaced → Enriched → Discussed → Actioned → Impact
> 9. Email the digest to me
> 10. Write a summary to `~/quick-kiro-handoff/` so Kiro stays in context
> 11. Notify me that the consolidated digest is ready
>
> Give it access to: Outlook (read + send to my email only), and file tools. Use the smart model. If it misses its scheduled time, run when next able.

---

## Step 4: Set Up Kiro's Research Hooks

Open Kiro and paste this prompt:

> I'm part of a two-agent system called BeaconIQ (v3). My role is the **Deep Researcher** — I browse internal web sources that Amazon Quick cannot access.
>
> **Please set up four hooks:**
>
> 1. **BeaconIQ Auto Research** — A `fileCreated` hook watching `~/quick-kiro-handoff/*beaconiq-research-request.md`. When Quick drops a signal file (Fridays at 3 PM), auto-trigger and process it.
>
> 2. **Run BeaconIQ Research** — A manual button in the Agent Hooks panel as a weekend fallback.
>
> 3. **BeaconIQ Log Outcome** — A manual button to log customer discussion outcomes. When triggered, ask me which recommendation I discussed, the customer's reaction (interested/neutral/not relevant), next steps, and business impact. Write to `~/quick-kiro-handoff/YYYY-MM-DD_kiro_beaconiq-outcome.md`.
>
> 4. **BeaconIQ QBR What's New** — A manual button to generate a "What's New for [Customer]" section for QBR/MBR prep using data from `~/quick-kiro-handoff/beaconiq-recommendation-history.json`.
>
> **When processing research signals (hooks 1 or 2), I should:**
> 1. Process **PFR-matched signals FIRST** (priority: critical) — these are highest value
> 2. Read all pending `*_quick_beaconiq-research-request.md` files from `~/quick-kiro-handoff/`
> 3. For each signal, browse the requested sources via Playwright MCP:
>    - **Highspot** (`highspot.com`) — battle cards, solution briefs, competitive intel. Pull **competitive battle cards** when Competitor Context is present in the signal.
>    - **Internal Wikis** (`w.amazon.com`, `wiki.amazon.com`) — feature specs, launch pages, FAQs
>    - **Partner Central** (`partnercentral.awspartner.com`) — partner updates, ISV launches
> 4. For PFR matches: write customer-ready talking points and offer to draft a SIFT insight
> 5. Detect **portfolio patterns** — if 3+ signals reference the same announcement, include a Portfolio Patterns section with suggested portfolio-level actions
> 6. Write findings to `~/quick-kiro-handoff/YYYY-MM-DD_kiro_beaconiq-enrichment.md`
>
> **Deadline:** All enrichment files must be written before Monday 10:00 AM for inclusion in that week's digest.

---

## Step 5: Create the Handoff README

Create a `README.md` in your handoff folder so both agents understand the v3 protocol.

**Mac:**
```bash
cat > ~/quick-kiro-handoff/README.md << 'EOF'
# Quick ↔ Kiro Handoff Directory — BeaconIQ v3

## File Types

| Pattern | Direction | Action |
|---------|-----------|--------|
| `*_quick_beaconiq-research-request.md` | Quick → Kiro | Standard research request (weekly) |
| `*_quick_beaconiq-urgent-enrichment-request.md` | Quick → Kiro | Urgent fallback — top items, depth: light |
| `*_kiro_beaconiq-enrichment.md` | Kiro → Quick | Research findings — Quick merges into digest |
| `*_kiro_beaconiq-enrichment-amendment.md` | Kiro → Quick | Post-hoc corrections to enrichment |
| `*_kiro_beaconiq-feedback.md` | Kiro → Quick | Scoring corrections, profile updates, dedup flags |
| `*_kiro_beaconiq-outcome.md` | Kiro → Quick | Recommendation outcome after customer discussion |
| `*_quick_beaconiq-digest.md` | Quick → Kiro | Digest summary (informational) |
| `beaconiq-customer-context-cache.md` | Shared | Customer context cache (either agent refreshes) |
| `beaconiq-watch-list.md` | Quick (maintained) | Preview services to watch for GA |
| `beaconiq-recommendation-history.json` | Quick → Kiro | 90-day recommendation history for QBR generation |

## Schedule

- **Friday 3 PM** — Quick scans, scores, writes research requests (PFR alerts sent immediately)
- **Friday PM – Monday AM** — Kiro processes signals (PFR first, then deep, then light)
- **Monday 10 AM** — Quick consolidates and delivers Excel digest + executive brief

## Signal Format v3 (Quick → Kiro)

```markdown
# Signal: beaconiq-research-request
**Date:** YYYY-MM-DD
**Source:** beaconiq-digest (Quick agent)
**Research Depth:** deep | light | verify
**Dedup ID:** lowercase-kebab-case
**PFR Match:** true | false
**Matched PFR:** <PFR ID> — <PFR Title>
**PFR Customer:** <name> (<account ID>)

## What Quick Found
<announcement details and matched customers>

## Competitor Context
- Customer: <name>
- Competitor: <name>
- Context: <brief description>

## Requested Action
<what to search in Highspot / wiki / Partner Central>

## Customer Context
<relevant customer details for targeted research>
```

## Enrichment Format (Kiro → Quick)

```markdown
# Output: beaconiq-enrichment
**Date:** YYYY-MM-DD
**In Response To:** <signal filename>
**Status:** completed

## Findings
### Highspot
<battle cards, briefs found>

### Wiki
<feature specs, launch pages found>

### Partner Central
<partner updates found>

### Competitive Positioning
<battle card findings, talk tracks — if competitor context was provided>

## Portfolio Patterns
<if 3+ signals share the same announcement>

## Prescriptive Enhancement
<how findings improve the recommendation>
```
EOF
```

**Windows (PowerShell):**
```powershell
@"
# Quick ↔ Kiro Handoff Directory — BeaconIQ v3

## File Types

| Pattern | Direction | Action |
|---------|-----------|--------|
| *_quick_beaconiq-research-request.md | Quick → Kiro | Standard research request (weekly) |
| *_quick_beaconiq-urgent-enrichment-request.md | Quick → Kiro | Urgent fallback — top items, depth: light |
| *_kiro_beaconiq-enrichment.md | Kiro → Quick | Research findings |
| *_kiro_beaconiq-enrichment-amendment.md | Kiro → Quick | Corrections to enrichment |
| *_kiro_beaconiq-feedback.md | Kiro → Quick | Scoring corrections, profile updates |
| *_kiro_beaconiq-outcome.md | Kiro → Quick | Outcome after customer discussion |
| *_quick_beaconiq-digest.md | Quick → Kiro | Digest summary (informational) |
| beaconiq-customer-context-cache.md | Shared | Customer context cache |
| beaconiq-watch-list.md | Quick (maintained) | Preview services watch list |
| beaconiq-recommendation-history.json | Quick → Kiro | 90-day history for QBR |

## Schedule

- Friday 3 PM — Quick scans, scores, writes research requests
- Friday PM – Monday AM — Kiro processes signals (PFR first)
- Monday 10 AM — Quick consolidates and delivers Excel digest + executive brief
"@ | Out-File -FilePath "$env:USERPROFILE\quick-kiro-handoff\README.md" -Encoding utf8
```

---

## AWSentral MCP Setup

BeaconIQ needs AWSentral MCP to pull your customer portfolio. If you haven't set it up:

1. **Install Builder Toolbox** — Visit https://w.amazon.com/bin/view/BuilderToolbox/
2. **Install Node.js** (v22+) — `brew install node` (Mac) or download from https://nodejs.org (Windows)
3. **Clone the MCP server** — Follow the AWSentral MCP setup guide on the internal wiki
4. **Configure in Quick** — Settings → Quick Suite → User MCP Servers → Add `aws-sentral-mcp`
5. **Authenticate** — Run `mwinit` to ensure your Midway session is active

---

## Customizing BeaconIQ

### Change the Schedule

Tell Quick:
> "Update my beaconiq-digest agent to run on [day] at [time]"
> "Update my beaconiq-consolidate agent to run on [day] at [time]"

### Change the Output Format

Tell Quick:
> "Update my beaconiq-consolidate agent to output HTML instead of Excel" (or DOCX, or both)

### Adjust Announcement Sources

Tell Quick:
> "Update my BeaconIQ Slack channels to include #channel-name"

### Focus on Specific Customers

Tell Quick:
> "Run BeaconIQ for [Customer Name] only"

### Run On-Demand

Say anytime in Quick:
> "What's new for my accounts?"
> "What's new for [Customer Name]?"
> "Run BeaconIQ for the last 30 days"

### Log a Customer Discussion Outcome

In Kiro, click the **"BeaconIQ Log Outcome"** button and provide:
- Which recommendation you discussed
- Customer reaction (interested / neutral / not relevant)
- Next steps taken
- Business impact (if any)

This feeds back into BeaconIQ's scoring to improve future recommendations.

### Generate QBR "What's New" Slides

In Kiro, click the **"BeaconIQ QBR What's New"** button and specify the customer name. Kiro generates a summary from the last 90 days of recommendations.

---

## Troubleshooting

| Problem | Solution |
|---|---|
| **Quick can't access Slack** | Settings → Integrations → reconnect Slack |
| **Quick can't access AWSentral** | Run `mwinit` to refresh Midway session |
| **Kiro's Playwright can't browse Highspot** | Ensure Playwright MCP is configured and you're logged into Highspot in Chrome |
| **No Pass 1 file on Monday** | beaconiq-digest may not have run Friday — trigger it manually: "Trigger my beaconiq-digest agent" |
| **Digest has no Kiro enrichments** | Kiro may not have been open Friday — use the manual "Run BeaconIQ Research" button |
| **Handoff folder not visible to Quick** | Add `~/quick-kiro-handoff` in Quick → Settings → Capabilities → Folders |
| **PFR alert not firing** | Ensure AWSentral MCP is connected — PFRs are pulled from Salesforce |
| **Outcome file not affecting scores** | Outcomes are ingested on the next Friday scanner run — check the following week's digest |

---

## What You Get

### Every Monday at 10 AM

| Channel | Details |
|---|---|
| **Desktop (Excel)** | `BeaconIQ_Digest_YYYY-MM-DD.xlsx` — 4 sheets: Summary, Recommendations, Portfolio Patterns, Announcements |
| **Desktop (Brief)** | `BeaconIQ_Brief_YYYY-MM-DD.md` — Executive brief with PFR resolutions + competitive positioning |
| **Email** | Digest sent to your Amazon email |
| **Notification** | Quick activity feed toast: "BeaconIQ digest ready" |

### Immediate (when PFR match found)

| Channel | Details |
|---|---|
| **Notification** | 🚨 "PFR Resolution Detected — [Customer]: [PFR Title] → [Announcement]. Call within 5 days." |

### Quarterly

| Channel | Details |
|---|---|
| **Effectiveness Report** | `BeaconIQ_Effectiveness_YYYY_QN.md` — funnel metrics, scoring accuracy, top-performing service areas |

### Recommendation Fields

| Field | Example |
|---|---|
| Title | Amazon Aurora Limitless Database — GA |
| Customer | Acme Corp |
| Relevance | 🔴 Critical (PFR match) / 🟢 High / 🟡 Medium |
| PFR Match | ✅ PFR-12345 — "Improved read scalability for Aurora" |
| Rationale | Customer runs Aurora PostgreSQL 14.6 with 3 read replicas. Open PFR for improved read scalability. |
| Guidance | Aurora Limitless directly addresses their PFR. Blue/Green migration path available. |
| Competitive | Customer evaluating Azure Cosmos DB — Aurora Limitless offers native PostgreSQL compatibility advantage. |
| Action | Call customer within 5 days. Add to next QBR. Schedule deep-dive with SA. |
| Sources | Slack #what-is-new, Highspot battle card, Wiki launch page |

---

## File Structure

```
Mac:    ~/quick-kiro-handoff/                     Windows: %USERPROFILE%\quick-kiro-handoff\
        ├── README.md
        ├── *_quick_beaconiq-research-request.md          (Quick → Kiro signals)
        ├── *_quick_beaconiq-urgent-enrichment-request.md  (Quick → Kiro urgent fallback)
        ├── *_kiro_beaconiq-enrichment.md                  (Kiro → Quick findings)
        ├── *_kiro_beaconiq-enrichment-amendment.md        (Kiro → Quick corrections)
        ├── *_kiro_beaconiq-feedback.md                    (Kiro → Quick scoring feedback)
        ├── *_kiro_beaconiq-outcome.md                     (Kiro → Quick customer outcomes)
        ├── *_quick_beaconiq-digest.md                     (digest summary)
        ├── beaconiq-customer-context-cache.md             (shared customer data cache)
        ├── beaconiq-watch-list.md                         (preview services watch list)
        └── beaconiq-recommendation-history.json           (90-day history for QBR)

Mac:    ~/Desktop/                                Windows: %USERPROFILE%\Desktop\
        ├── BeaconIQ_Pass1_YYYY-MM-DD.json                 (intermediate results)
        ├── BeaconIQ_Digest_YYYY-MM-DD.xlsx                (weekly digest — 4 sheets)
        ├── BeaconIQ_Brief_YYYY-MM-DD.md                   (executive brief)
        └── BeaconIQ_Effectiveness_YYYY_QN.md              (quarterly report)
```

---

## Questions or Feedback?

This solution was built using Amazon Quick Desktop and Kiro IDE with zero cloud infrastructure. If you have ideas to improve BeaconIQ, reach out or fork the setup for your own team.

Built by Sino Yousef | April 2026 | v3