AI-Powered Executive Review System
Build a standing MBR/QBR system with Claude agents that holds up under live VP scrutiny.
Introduction
30 Second Summary
Every executive review has a moment where someone challenges a number. If you can't trace it back to a written definition on the spot, you lose the room.
In this project, you will build a standing executive review system powered by a swarm of Claude agents. The system assembles monthly and quarterly business review decks from a single metric-definition ledger, automates the review cadence, and proves its integrity when you survive a live dispute on a headline number.
What You'll Build
A complete AI-orchestrated executive review operating system with agent-assembled decks, a metric governance ledger, automated cadence triggers, and a validated dispute-reconciliation capability.
By the end of this project, you'll have:
- A standing executive review rhythm (MBR + QBR) with decks assembled by 10+ Claude Code agents using fan-out, pipeline, and verify-then-merge orchestration patterns.
- A metric-definition ledger in Google Sheets where every number in every deck traces to a written definition ratified by a human owner.
- A two-tier automated cadence with pre-briefs, input deadlines, n8n workflow triggers, Google Calendar schedule, and a complete RACI.
- A validated dispute-reconciliation record proving you held the room on a challenged metric by tracing it to the ledger on the spot.
- Secret Mission: Add a pre-mortem agent that identifies the three metrics most likely to be disputed before each review and pre-writes the reconciliation path.
Are there any prerequisites?
You need a Claude Max subscription (covers Claude Code at flat rate), a Linear workspace with at least one team and issues, a Google account for Sheets and Calendar, Node.js v18+, and an n8n instance (self-hosted free tier or cloud free trial).
If your team uses Jira instead of Linear, you can substitute it throughout. You also need access to your current-quarter objectives in an OKR tool (Quantive, WorkBoard, or similar). If no OKR tool is in use, you will enter objectives manually into the ledger.
Before We Start
You are about to build something most TPMs talk about but never systematize: a standing executive review operating system that makes every number in the room traceable to a written definition.
This step wires up the environment you need. You will confirm your Claude Code access, install the deck-generation toolchain, create the project structure, and set up the metric ledger and cadence calendar that everything else will run on.
In this step, get ready to:
- Verify Claude Code and Linear access.
- Install Marp CLI and initialize the project directory.
- Set up the metric ledger and cadence calendar in Google.
Verify Claude Code and Linear access
Claude Code is the orchestrator that will coordinate your agent swarm. Before you build anything, confirm it is installed and authenticated on your machine.
- Open your terminal by pressing Cmd+Space (macOS) or the Windows key (Windows), then typing Terminal and pressing Enter.
- Check that Claude Code is installed by running this command:
claude --version✔️ I see a version number
Claude Code is installed and ready. Move on to the Linear verification below.
ⓧ Command not found
Claude Code is not installed yet. Install it using the native installer for your platform.
macOS
- Install Claude Code by running:
curl -fsSL https://claude.ai/install.sh | sh- Close and reopen your terminal, then run claude --version again to confirm.
Windows
- Install Claude Code by running this in PowerShell:
irm https://claude.ai/install.ps1 | iex- Close and reopen your terminal, then run claude --version again to confirm.
- Verify your Linear workspace by logging in at linear.app and confirming you have at least one team with issues visible.
- If your team uses Jira instead, confirm you have API access to your Jira instance with read permissions on projects and issues.
- Verify your OKR source: confirm you can access your current-quarter objectives in Quantive, WorkBoard, or whatever tool your org uses.
- If no OKR tool is in use, note that you will enter objectives manually into the ledger in a later step.
What counts as verified here?
Claude Code returns a version string. Linear (or Jira) loads with visible projects and cycles. Your OKR source is accessible or noted as manual entry.
Install Marp CLI and initialize the project repo
Marp CLI converts markdown slide decks into PDF. It requires Node.js v18 or later.
- Check your Node.js version by running:
node --version✔️ I see v18 or higher
Your Node.js version is sufficient. Continue to the Marp CLI install below.
ⓧ I see an older version
You need Node.js v18 or higher for Marp CLI. Visit nodejs.org and download the LTS installer for your platform.
After installing, close and reopen your terminal, then run node --version again to confirm the version starts with v18 or higher.
ⓧ Command not found
Node.js is not installed. Visit nodejs.org and download the LTS installer for your platform.
After installing, close and reopen your terminal, then run node --version to confirm it returns v18 or higher.
- Install Marp CLI globally by running:
npm install -g @marp-team/marp-cli- Verify the installation by running:
marp --versionSeeing a permission error?
On macOS or Linux, you may need to prefix the install command with sudo. On Windows, try running PowerShell as Administrator.
help me fix a permission error when installing Marp CLI with npm
Now create the project directory. This folder will hold your agent definitions, decks, ledger exports, cadence specs, and documentation.
- Move to your Desktop by running this command:
cd ~/Desktop- Create the project folder and all subdirectories by running:
macOS
mkdir hold-the-room
cd hold-the-room
mkdir -p .claude/agents decks ledger cadence docs- Confirm the folders exist by running:
lsYou should see cadence, decks, docs, and ledger in the output. The .claude folder is hidden. Confirm it exists by running:
ls -aYou should see .claude listed.
Windows
mkdir hold-the-room
cd hold-the-room
mkdir .claude\agents
mkdir decks
mkdir ledger
mkdir cadence
mkdir docs- Confirm the folders exist by running:
lsYou should see cadence, decks, docs, ledger, and .claude in the output.
What is this folder structure for?
.claude/agents/ holds the scoped system prompts for each agent in your review swarm. decks/ stores the Marp markdown and compiled PDFs.
ledger/ holds local exports of your metric definitions. cadence/ stores the standing-cadence spec and RACI. docs/ holds architecture decision records, the topology diagram, and readout documents.
Set up the metric ledger and the cadence calendar
The metric-definition ledger is the single source of truth for every number that will appear in your review decks. You will create it in Google Sheets so every agent (and every human) references the same definitions.
- Open Google Sheets at sheets.google.com.
- Create a new spreadsheet and name it Metric Definition Ledger.
- Rename the first tab to Definitions.
- In the first row of the Definitions tab, enter these column headers:
- Metric ID, Metric Name, Definition, Owner, Source System, Target, Threshold Amber, Threshold Red, Calculation Method, Last Ratified.
- Add a second tab and name it Decision Log.
- In its first row, enter these column headers:
- Decision ID, Date, Review Type, Decision, Owner, Due Date, Status.
- Add a third tab and name it Dispute Record.
- In its first row, enter these column headers:
- Dispute ID, Date, Metric Challenged, Challenger, Definition Pulled, Calculation Shown, Resolution, Logged By.
Why three tabs?
The Definitions tab is the source of truth for what every metric means, who owns it, and how it is calculated. The Decision Log captures every decision from a live review so nothing falls through the cracks.
The Dispute Record logs any challenge to a headline number and its resolution. This is the governance proof that you can hold the room on evidence.
Now set up the cadence calendar so your reviews have a standing schedule.
- Open Google Calendar at calendar.google.com.
- Click the + next to Other calendars in the left sidebar.
- Select Create new calendar.
- Name it Executive Review Cadence and click Create calendar.
- Create a recurring monthly event named MBR on a day of your choice. Set the recurrence to monthly.
- Create a recurring quarterly event named QBR in the last week of the current quarter. Set the recurrence to every 3 months.
- Create a separate event named MBR Input Deadline set 2 business days before your MBR. Set it to recur monthly.
- Create a separate event named QBR Input Deadline set 5 business days before your QBR. Set it to recur every 3 months.
Why input deadlines as separate events?
Input deadlines are the triggers that tell program owners to finalize their status data. In a later step, these will map to n8n automation triggers that notify owners and kick off the agent data-collection fan-out.
Calendar not appearing in your sidebar?
After creating the calendar, make sure Executive Review Cadence is checked in the left sidebar under Other calendars. It may take a moment to appear.
help me find my newly created Google Calendar
Your environment is wired. Next up, you will design the agent architecture and roster that will power your review system.
Wire the Environment
Executive reviews stand or fall on evidence, and evidence requires infrastructure. Before building the agent roster that assembles your decks, you need a working environment where every tool connects cleanly.
In this step, you'll confirm your Claude Code and Linear access, install the deck-generation toolchain, create the project structure, and set up the data infrastructure that backs every metric in every review.
In this step, get ready to:
- Verify Claude Code, Linear, and OKR access.
- Install Marp CLI and initialize the project directory.
- Set up the metric-definition ledger and the cadence calendar.
Verify Claude Code and Linear access
The review system you're building depends on three data sources: Claude Code for agent orchestration, your Linear workspace for program delivery metrics, and your OKR tool for outcome scoring. Confirming access now prevents cryptic failures later.
- Open a terminal by pressing Cmd+Space (macOS) or the Windows key (Windows), then type Terminal and press Enter.
- Confirm Claude Code is working by running this command:
claude --versionWhat should I see?
You should see a version string followed by (Claude Code) printed to your terminal. This confirms your Claude Max subscription includes Claude Code access and authentication is working.
- Open your browser and log into your Linear workspace.
- Confirm you can see at least one team with issues in it.
Using Jira instead?
If your team uses Jira instead of Linear, confirm you have API access to your Jira instance with read permissions on projects and issues. The exercise references Linear throughout, but the same data (velocity, cycle time, scope change) is available from Jira.
- Verify your OKR source: confirm you can access your current-quarter objectives in your OKR tool (such as Quantive or WorkBoard).
- If your organization does not use an OKR tool, note this down. You will enter objectives manually into the metric ledger in a later step.
Claude Code not returning a version?
Make sure your Claude Max subscription is active. Claude Code is included with both the $100/month and $200/month Max plans.
If you see a command not found error, Claude Code may not be installed. Visit the Claude Code documentation for installation instructions specific to your operating system.
Help me troubleshoot my Claude Code installation
Install Marp CLI and initialize the project repo
Your review decks will be written as Marp markdown and compiled to PDF. Marp CLI handles that conversion directly from the terminal with no API keys or OAuth setup needed.
- Confirm your Node.js version is v18 or higher by running:
node --version✔️ I see v18 or higher
Your Node.js version meets the requirement. Continue to the Marp CLI installation below.
ⓧ I see a version lower than v18
Marp CLI requires Node.js v18 or later. You need to upgrade before continuing.
- Visit the official Node.js downloads page at nodejs.org and download the LTS installer for your operating system.
- Run the installer, which will replace your existing version.
- Close and reopen your terminal, then run node --version again to confirm v18 or higher.
ⓧ Command not found
Node.js is not installed on your machine.
- Visit the official Node.js downloads page at nodejs.org and download the LTS installer for your operating system.
- Run the installer and accept the defaults.
- Close and reopen your terminal, then run node --version to confirm v18 or higher is returned.
- Install Marp CLI globally by running this command:
npm install -g @marp-team/marp-cli- Verify the installation by running:
marp --versionWhat does Marp CLI do?
Marp converts markdown files into presentation slides. Your Claude agents will write deck content as markdown, and Marp compiles it directly to PDF.
This avoids the overhead of Google Slides API authentication and template management. Decks stay version-controlled alongside your agent definitions.
Marp install failed?
If you see a permissions error on macOS, prefix the command with sudo and enter your system password when prompted.
If npm itself is not found, revisit the Node.js installation above. The npm command ships with every Node.js installation.
Help me fix my Marp CLI installation
Now create the project directory structure that will hold your agent definitions, decks, and governance documents.
- Move to your Desktop by running this command:
cd ~/Desktop- Create your project folder and move into it by running these commands:
mkdir hold-the-room
cd hold-the-room- Create the subdirectories by running:
macOS
mkdir -p .claude/agents decks ledger cadence docsWindows
mkdir .claude/agents, decks, ledger, cadence, docs- Confirm the directories exist by running:
lsYou should see decks, ledger, cadence, and docs listed. The .claude directory is hidden by default.
- Confirm the hidden .claude/agents directory exists by running:
ls .claude/agentsThis should return without an error, confirming the nested directory was created.
What is each directory for?
- .claude/agents/ holds agent definition files (scoped system prompts for each agent role).
- decks/ stores the Marp markdown and compiled PDF output for MBR and QBR decks.
- ledger/ holds local copies or exports from the metric-definition ledger.
- cadence/ stores the cadence spec, RACI, and n8n workflow definitions.
- docs/ holds architecture decision records, the topology diagram, and readout documents.
Set up the metric ledger and the cadence calendar
Every number in every deck must trace to a single source of truth. The metric-definition ledger is that source: one Google Sheets workbook where every metric carries a written definition, owner, and calculation method.
- Open Google Sheets at sheets.google.com.
- Click Blank spreadsheet to create a new sheet.
- Rename the spreadsheet to Metric Definition Ledger by clicking the title in the top-left corner and typing the new name.
Now set up the three tabs that structure your governance data.
- Rename the default tab (Sheet1) to Definitions by double-clicking the tab name at the bottom of the screen.
- In row 1 of the Definitions tab, enter these column headers across cells A1 through J1:
Metric ID | Metric Name | Definition | Owner | Source System | Target | Threshold Amber | Threshold Red | Calculation Method | Last RatifiedWhy these columns?
Each column serves a governance purpose. Definition is what you cite when a VP challenges the number. Owner is the human who ratifies the definition (never an agent). Calculation Method is the exact formula you walk in the room.
The amber and red thresholds drive the traffic-light status on your deck slides. Last Ratified proves the definition is current, not stale.
- Click the + icon at the bottom of the screen to add a new tab.
- Rename it to Decision Log.
- In row 1, enter these column headers across cells A1 through G1:
Decision ID | Date | Review Type | Decision | Owner | Due Date | Status- Add one more tab by clicking + again.
- Rename it to Dispute Record.
- In row 1, enter these column headers across cells A1 through H1:
Dispute ID | Date | Metric Challenged | Challenger | Definition Pulled | Calculation Shown | Resolution | Logged ByWhat is the Dispute Record for?
When a VP challenges a number in the room, you pull the definition from the ledger and walk the calculation. The Dispute Record logs exactly what was challenged, what you showed, and how it was resolved.
This is your governance proof: evidence that numbers are defensible and disputes are resolved on the spot, not papered over.
Next, set up the standing calendar that drives the review cadence.
- Open Google Calendar at calendar.google.com.
- Click the + next to Other calendars in the left sidebar.
- Select Create new calendar.
- Name it Executive Review Cadence and click Create calendar.
Now add the recurring review events and input-deadline reminders.
- Create a new event on your chosen monthly review day.
- Title it Monthly Business Review (MBR).
- Set it to repeat monthly on the same day.
- Make sure the event is on the Executive Review Cadence calendar (select it from the calendar dropdown in the event editor).
- Save the event.
- Create a second recurring event for the quarterly review.
- Title it Quarterly Business Review (QBR).
- Set it to repeat quarterly (every 3 months), typically in the last week of the quarter.
- Save the event.
- Create input-deadline reminder events:
- Add a recurring monthly event titled MBR Input Deadline set 2 business days before your MBR date.
- Add a recurring quarterly event titled QBR Input Deadline set 5 business days before your QBR date.
- Save both events.
Why input deadlines?
The input deadline is the data-freeze point. After this date, program owners must have their status finalized in Linear. Your n8n automation (built later) will use these dates as triggers to kick off metric collection.
Without a freeze point, numbers shift between when you build the deck and when you present it. That is how disputed numbers are born.
Confirm your setup: you should see three tabs with headers in your Google Sheet, and four recurring events visible on your Executive Review Cadence calendar (MBR, QBR, MBR Input Deadline, QBR Input Deadline).
Your environment is wired. Next up, you'll define the agent architecture and build the roster that turns this infrastructure into an automated review system.
Build the Architecture and Agent Roster
Your environment is wired and your ledger is ready. Now you need to decide how the system will work before you build it.
In this step, you will design the multi-agent architecture that powers the entire review system. You will define 10 specialized agents, document the architectural decisions that govern them, and map the end-to-end data flow so every future step has a blueprint to follow.
In this step, get ready to:
- Define 10 agent roles with scoped system prompts and restricted tool access.
- Write two Architecture Decision Records documenting the agent and metric governance patterns.
- Produce a Mermaid topology and a six-phase implementation plan.
Define the agent roster and write the ADRs
Claude Code uses subagents to delegate specialized work. Each subagent is a markdown file in .claude/agents/ with YAML frontmatter (name, description, tools) and a system prompt body.
Your review system needs 10 agents organized into three layers: data collection, content generation, and governance.
What is a Claude Code subagent?
A subagent is a specialized AI assistant that runs in its own context with a dedicated system prompt and restricted tool access. The orchestrator (your main Claude Code session) delegates tasks to subagents automatically based on their descriptions.
Each subagent file uses YAML frontmatter to declare its name, description, and tools. The markdown body below the frontmatter becomes the agent's system prompt.
- Create the first agent definition file by saving the following content to .claude/agents/metric-collector.md:
---
name: metric-collector
description: Reads Linear (or Jira) data for a given project/team and returns structured metrics. Use when collecting velocity, cycle time, scope change, or completion rate data for a review.
tools: Read, Grep, Glob, LS
---
# Metric Collector Agent
You are a data collection specialist for executive business reviews.
## Role
Read Linear (or Jira) project data for a specified team or project. Return structured metrics as JSON.
## Output Format
Return one JSON object per metric:
```json
{"metric_id": "string", "value": "number", "period": "string", "source_url": "string"}
```
## Constraints
- You are READ-ONLY. Never modify source data.
- Collect only: velocity, cycle time, lead time, scope change rate, completion rate.
- If a metric cannot be computed from available data, return null with an explanation.
- Never invent or estimate values. Report only what the data shows.
## Context
The orchestrator fans out one instance of you per team/project. Your output feeds the metric-reconciler for validation against the definition ledger.What does this file do?
The YAML frontmatter tells Claude Code when to use this agent (description) and what it can do (tools: Read, Grep, Glob, LS means read-only access). The body gives the agent its instructions: what to collect, how to format it, and what it must never do.
- Create the remaining nine agent files following the same pattern. Save each to .claude/agents/ with the filename shown below.
Save this content to .claude/agents/metric-reconciler.md:
---
name: metric-reconciler
description: Cross-references collected metrics against the definition ledger. Flags any metric computed differently from its written definition. Use after metric collection completes.
tools: Read, Grep, Glob, LS
---
# Metric Reconciler Agent
You are a verification specialist ensuring metric integrity.
## Role
Cross-reference each collected metric against the Metric Definition Ledger. For each metric, verify:
1. The calculation method matches the written definition.
2. The source system matches the declared source.
3. The value falls within plausible bounds given the target and thresholds.
## Output Format
For each metric, return: PASS (definition matches) or FLAG (discrepancy found, with explanation).
## Constraints
- You are READ-ONLY. Never modify the ledger or the collected data.
- Never resolve discrepancies yourself. Flag them for operator review.
- If a metric has no matching definition in the ledger, flag it as an orphan.Save this content to .claude/agents/narrative-drafter.md:
---
name: narrative-drafter
description: Takes validated metrics and writes the executive narrative for a given review section. Honest status reporting only. Use after reconciliation is complete.
tools: Read, Write, Edit, Bash
---
# Narrative Drafter Agent
You are an executive communication specialist for business reviews.
## Role
Take validated metrics and write the executive narrative for a given deck section (status, risks, decisions needed).
## Principles
- Honest status: amber is reported amber. Red includes a recovery recommendation.
- An all-green portfolio deserves scrutiny. Flag it if data supports concern.
- Every section ends with a decision or an explicit no-decision.
- Any uncertain figure is labeled an estimate.
## Write Access
You may write to decks/ only. Never modify the ledger or source data.
## Output
Markdown formatted for Marp slides. One section per invocation.Save this content to .claude/agents/pre-brief-drafter.md:
---
name: pre-brief-drafter
description: Takes the full deck narrative and a stakeholder profile. Produces a tailored pre-brief removing surprises so the room can focus on decisions. Use before each review.
tools: Read, Write, Edit, Bash
---
# Pre-Brief Drafter Agent
You produce tailored pre-brief documents for each decision-making stakeholder.
## Role
Given the compiled deck narrative and a stakeholder profile, produce a document that:
1. States what the stakeholder cares about.
2. Flags what might surprise them.
3. Names the decisions they will be asked to make.
## Audience Variants
- VP/Sponsor: Outcomes, investment decisions, red items with recommendations.
- Finance: Budget variance, resource utilization, ROI metrics.
- Program Owners: Their specific program status, what they will be asked to decide.
## Constraints
- The pre-brief is not spin. It removes surprises.
- Write access to decks/ only.Save this content to .claude/agents/deck-compiler.md:
---
name: deck-compiler
description: Assembles section outputs into Marp-formatted slide markdown with correct frontmatter. Use after narrative drafting is complete.
tools: Read, Write, Edit, Bash
---
# Deck Compiler Agent
You assemble review deck sections into a complete Marp presentation.
## Role
Take section outputs from the narrative-drafter and compile them into a single Marp markdown file with:
- Correct frontmatter (theme: default)
- Page separators (---)
- Consistent formatting across slides
## Output Structure
- Slide 1: Title + date + review type
- Body slides: One per section, with metrics and decisions
- Final slide: Decisions and actions summary
## Constraints
- Write access to decks/ only.
- Never modify metric values. Use exactly what the narrative-drafter provided.
- Ensure every metric on a slide traces to a ledger row.Save this content to .claude/agents/dispute-rehearsal.md:
---
name: dispute-rehearsal
description: Plays a skeptical VP. Given the deck and ledger, picks the most challengeable metric and disputes it. Use for pre-review rehearsal.
tools: Read, Grep, Glob, LS
---
# Dispute Rehearsal Agent
You are a skeptical executive challenging the review deck.
## Role
Read the completed deck and the metric ledger. Identify the most challengeable metric and dispute it in the voice of a VP who:
- Questions the measurement window
- Challenges the calculation method
- Suspects cherry-picking
## Output
A pointed challenge (2-3 sentences) that the operator must respond to using only the ledger definition.
## Constraints
- You are READ-ONLY. You cannot see the operator's planned response.
- Pick metrics with: large period-over-period change, recent definition updates, or known data-quality concerns.
- Be specific and adversarial but fair.Save this content to .claude/agents/decision-log-keeper.md:
---
name: decision-log-keeper
description: Records every decision from a review into the decision log format. Use during or after each review session.
tools: Read, Write, Edit, Bash
---
# Decision Log Keeper Agent
You record decisions made during executive reviews.
## Role
Capture every decision from the review session and write it to the Decision Log tab format.
## Output Format
For each decision: Decision ID, Date, Review Type (MBR/QBR), Decision text, Owner, Due Date, Status (open/closed).
## Constraints
- Write access to ledger/ only.
- Never interpret or editorialize decisions. Record exactly what was decided.
- If a decision has no clear owner, flag it for the operator.Save this content to .claude/agents/cadence-scheduler.md:
---
name: cadence-scheduler
description: Produces the standing cadence spec including dates, input deadlines, owners per section, RACI, and n8n workflow triggers. Use when setting up or updating the review cadence.
tools: Read, Write, Edit, Bash
---
# Cadence Scheduler Agent
You produce and maintain the standing cadence specification for executive reviews.
## Role
Generate the cadence spec covering:
1. MBR and QBR schedules with specific dates.
2. Input deadlines (data freeze) for each review type.
3. Owner assignments per section.
4. n8n workflow trigger definitions.
5. Google Calendar event specifications.
## Constraints
- Write access to cadence/ only.
- Dates must align with the team's existing sprint/cycle cadence.
- Every activity must have exactly one R (Responsible) in the RACI.Save this content to .claude/agents/okr-scorer.md:
---
name: okr-scorer
description: Reads objectives from the OKR tool or manual ledger entries and computes attainment percentage for the QBR scorecard. Use during QBR preparation.
tools: Read, Grep, Glob, LS
---
# OKR Scorer Agent
You compute objective attainment for quarterly business reviews.
## Role
Read current-quarter objectives from the OKR tool (Quantive/WorkBoard) or from manual entries in the metric ledger. Compute attainment % for each outcome metric.
## Output Format
For each objective: Objective name, Key Result, Target, Actual, Attainment %.
## Constraints
- You are READ-ONLY. Never modify objectives or targets.
- If an objective has no measurable key result, flag it rather than estimating.
- Attainment calculations must match the method recorded in the ledger.Save this content to .claude/agents/executive-summary-drafter.md:
---
name: executive-summary-drafter
description: Produces the one-page read-ahead for sponsors. Portfolio state in 2 minutes, honest status, and the decisions the room will be asked to make. Use before each review.
tools: Read, Write, Edit, Bash
---
# Executive Summary Drafter Agent
You produce the one-page executive read-ahead.
## Role
Create a summary that a sponsor can read in 2 minutes and walk into the review prepared. Include:
1. Portfolio state (traffic-light per program).
2. Honest status (no false green).
3. The 3 decisions the room will be asked to make.
## Constraints
- Write access to decks/ only.
- One page maximum. If it needs two pages, cut.
- Any uncertain figure is labeled an estimate.- Confirm all 10 agent files exist by running:
ls .claude/agents/You should see all 10 files listed: metric-collector.md, metric-reconciler.md, narrative-drafter.md, pre-brief-drafter.md, deck-compiler.md, dispute-rehearsal.md, decision-log-keeper.md, cadence-scheduler.md, okr-scorer.md, executive-summary-drafter.md.
Why three layers of agents?
The roster is organized by trust boundaries. Collection agents (metric-collector, okr-scorer) are read-only because they touch source data. Pipeline agents (narrative-drafter, deck-compiler, pre-brief-drafter, executive-summary-drafter) can write to decks/ only. Governance agents (decision-log-keeper, cadence-scheduler) write to ledger/ or cadence/ only.
The metric-reconciler sits between collection and pipeline as a verification gate. No metric reaches the narrative without passing through reconciliation. The dispute-rehearsal agent is adversarial and intentionally read-only so it cannot see its own answer.
Agent not appearing in Claude Code?
Make sure your agent file is saved inside .claude/agents/ at the project root (hold-the-room/.claude/agents/). Claude Code scans this directory automatically. Also confirm the YAML frontmatter has both name and description fields. Missing either will prevent the agent from loading.
help me troubleshoot why my agent file isn't being detected by Claude Code
Now document the architectural decisions that govern these agents. These ADRs are the design rationale that future maintainers (including your future self) will reference.
- Create the first Architecture Decision Record by saving the following to docs/adr-001-agent-architecture.md:
# ADR-001: Multi-Agent Architecture for Business Review Assembly
## Status
Accepted
## Context
Assembling a monthly or quarterly business review requires collecting metrics from multiple programs, validating them against definitions, drafting narratives, producing pre-briefs for each stakeholder, and compiling everything into a presentation. A single-agent approach would exhaust context windows and produce inconsistent quality across sections.
## Decision
Adopt a multi-agent orchestration pattern with three coordination styles:
1. **Fan-out** for metric collection: one collector agent per program/team, running in parallel. The orchestrator (main Claude Code session) spawns collectors and gathers results.
2. **Pipeline** for content generation: narrative-drafter > pre-brief-drafter > deck-compiler. Each stage depends on the previous stage's output.
3. **Verify-then-merge** for metric reconciliation: an independent reconciler validates every collected metric against the definition ledger before it reaches the narrative. Flagged metrics require operator ratification.
Each agent has scoped tool access:
- Collection agents: read-only (Read, Grep, Glob, LS)
- Pipeline agents: write to decks/ only
- Governance agents: write to ledger/ or cadence/ only
## Consequences
- All metric outputs pass through the reconciler before reaching the narrative. No orphan numbers.
- The operator ratifies definitions and resolves flags. Agents do not ratify their own output.
- Agents are leverage, not authority. The system amplifies the operator's judgment. It does not replace it.
- Adding a new program to the portfolio requires only spawning an additional collector instance. The architecture scales horizontally.What is an Architecture Decision Record?
An ADR captures a significant design choice with its context (why the decision was needed), the decision itself, and its consequences. Anyone reading the ADR later understands not just what was chosen, but why alternatives were rejected.
ADRs are standard practice in engineering organizations. They prevent knowledge loss when team members rotate and provide a reference point when assumptions are later questioned.
- Create the second ADR by saving the following to docs/adr-002-metric-governance.md:
# ADR-002: Single-Ledger Metric Governance
## Status
Accepted
## Context
A number must mean the same thing in both the MBR and QBR rooms. If "cycle time" is measured from 'In Progress' in the MBR but from 'Ready for Dev' in the QBR, executives will challenge the inconsistency and trust collapses. Multiple definitions of the same metric across different decks is the single largest source of credibility loss in program reviews.
## Decision
Establish the Google Sheet "Metric Definition Ledger" as the single source of truth for all metrics used in any review. Every metric carries:
- A written definition (plain-language description of what is measured)
- A named human owner (not an agent)
- A declared source system
- A target and amber/red thresholds
- A calculation method (exact formula or query logic)
- A last-ratified date
Metric definitions are ratified by a human owner. Agents never invent metrics, define targets, or modify calculation methods.
## Consequences
- No orphan numbers appear in any deck. Every figure traces to a ledger row.
- Dispute resolution traces to the ledger: pull the definition, walk the calculation, confirm or update.
- Definition updates are logged with date and approver. The audit trail is the proof of governance.
- Adding a new metric requires a human owner to write and ratify the definition before any agent can collect it.- Confirm both ADR files exist by running:
ls docs/You should see adr-001-agent-architecture.md and adr-002-metric-governance.md in the output.
Why design before build?
Writing the ADRs before creating any deck or running any agent forces you to think through the trust model, the data flow, and the failure modes. When the dispute-rehearsal agent challenges a number in Step 5, the answer is already documented here.
Produce the Mermaid topology and implementation plan
The topology is the visual blueprint that shows how agents, data sources, and tools connect. It makes the abstract architecture from ADR-001 concrete and verifiable.
- Create the end-to-end topology diagram by saving the following to docs/topology.mmd:
flowchart LR
%% Data Sources
subgraph Sources[Data Sources]
Linear[(Linear Projects)]
OKR[(OKR Tool)]
end
%% Fan-out: Collection Layer
subgraph Collection[Fan-Out: Collection]
MC1[metric-collector\nTeam 1]
MC2[metric-collector\nTeam 2]
MC3[metric-collector\nTeam N]
OKS[okr-scorer]
end
%% Verify-then-merge
subgraph Verification[Verify-Then-Merge]
MR[metric-reconciler]
Ledger[(Metric Definition Ledger)]
end
%% Pipeline: Content Generation
subgraph Pipeline[Pipeline: Content Generation]
ND[narrative-drafter]
ESD[executive-summary-drafter]
DC[deck-compiler]
PBD[pre-brief-drafter]
end
%% Governance and Validation
subgraph Governance[Governance]
DR[dispute-rehearsal]
DLK[decision-log-keeper]
CS[cadence-scheduler]
end
%% Outputs
subgraph Outputs[Deliverables]
MBR[MBR Deck PDF]
QBR[QBR Deck PDF]
PreBriefs[Pre-Brief Docs]
DecLog[Decision Log]
CadSpec[Cadence Spec]
Calendar[Google Calendar]
end
%% Connections: Sources to Collection
Linear --> MC1
Linear --> MC2
Linear --> MC3
OKR --> OKS
%% Collection to Verification
MC1 --> MR
MC2 --> MR
MC3 --> MR
OKS --> MR
Ledger --> MR
%% Verification to Pipeline
MR --> ND
MR --> ESD
ND --> DC
ESD --> DC
DC --> PBD
%% Pipeline to Outputs
DC --> MBR
DC --> QBR
PBD --> PreBriefs
%% Governance connections
DC --> DR
DR -.->|challenges| MR
DLK --> DecLog
CS --> CadSpec
CS --> CalendarWhat does this topology show?
The diagram maps all three orchestration patterns from ADR-001. Data flows left-to-right: sources feed collectors (fan-out), collectors feed the reconciler (verify-then-merge), reconciled metrics feed the narrative and deck pipeline (sequential), and the dispute agent validates the finished deck.
The dashed line from dispute-rehearsal back to the reconciler shows that a challenged metric traces back to its definition. The governance agents (bottom) produce their outputs independently after the review runs.
- Verify the topology renders without errors by pasting it into mermaid.live.
- Open your browser and navigate to mermaid.live.
- Paste the contents of docs/topology.mmd into the editor panel on the left.
- Confirm the diagram renders in the preview panel on the right with no error messages.
Diagram not rendering?
Check for unescaped special characters in node labels. Mermaid is strict about syntax. Common issues include missing closing brackets on node definitions and using direction TD inside subgraphs (use direction TB instead). Also confirm you are using flowchart LR at the top, not graph LR.
help me fix a Mermaid syntax error in my topology diagram
Finally, create the implementation plan that sequences the rest of this build and the post-session adoption work.
- Create the plan by saving the following to docs/implementation-plan.md:
# Implementation Plan
Drawn from ADR-001 (agent architecture) and ADR-002 (metric governance).
## Phase 1: Environment and Architecture (Steps 1-2, this session)
- Wire development environment (Claude Code, Linear, Google Sheets, Marp CLI)
- Define agent roster with scoped system prompts and tool access
- Write Architecture Decision Records
- Produce Mermaid topology and this implementation plan
**Exit criteria:** 10 agent files, 2 ADRs, topology renders, plan exists.
## Phase 2: Metric Tree and Cadence Design (Step 3, this session)
- Build the three-tier metric tree (outcomes > delivery > leading)
- Populate the metric-definition ledger with 8+ metrics from real Linear data
- Design the two-tier cadence (MBR monthly, QBR quarterly)
- Produce the n8n workflow spec and RACI
**Exit criteria:** Metric tree renders, ledger populated, cadence spec complete, RACI has no unassigned cells.
## Phase 3: Agent-Assembled Review Kit (Step 4, this session)
- Run metric-collection fan-out against Linear workspace
- Run OKR scorer against objectives source
- Execute metric reconciliation (verify-then-merge)
- Generate MBR and QBR decks (Marp markdown to PDF)
- Generate pre-briefs and executive summary
**Exit criteria:** MBR and QBR PDFs render, every metric traces to ledger, pre-briefs exist per stakeholder.
## Phase 4: Live Review and Closing Readout (Step 5, this session)
- Run dispute-rehearsal agent against finished QBR deck
- Operator responds using only ledger definitions
- Log decisions and dispute resolution
- Produce two-audience closing readout (delivery + executive)
- Conduct retrospective
**Exit criteria:** Dispute record complete, decision log has entries, both readouts exist, next review dates set.
## Phase 5: First Real MBR (Day 1-30, post-session)
- Deploy n8n workflow with input-deadline triggers
- Run first real MBR on schedule against live portfolio data
- Iterate agent prompts based on real output quality
- Share ledger with RACI-designated owners
**Exit criteria:** One complete MBR delivered to delivery leadership on schedule.
## Phase 6: First Real QBR and Ledger Acceptance (Day 30-90, post-session)
- Run first real QBR with executive sponsor
- Metric-definition ledger accepted as organizational source of truth
- Standing cadence confirmed operational
- Pre-mortem agent (Secret Mission) added to cadence if completed
**Exit criteria:** QBR delivered, ledger is the accepted source of truth, cadence repeats without operator heroics.Why six phases?
Phases 1-4 are this session (the build). Phase 5 is the first real use (proving the system works with live data). Phase 6 is organizational acceptance (proving the system sustains without heroics). This distinction matters because building a review system is easy. Getting an organization to trust it takes 90 days.
- Confirm all four docs files exist by running:
ls docs/You should see: adr-001-agent-architecture.md, adr-002-metric-governance.md, topology.mmd, and implementation-plan.md.
Your architecture is documented and your agent roster is defined. Next up, you will design the operating rhythm that makes this system repeatable: the metric tree, the two-tier cadence, and the RACI that assigns every activity to a named human.
Design the Operating Rhythm
Your architecture is in place. You have ten agents defined, two ADRs governing their behavior, and a topology showing how data flows between them.
Now you need the content those agents will actually work with. A review system without defined metrics is just a meeting with slides. In this step, you will build the metric tree that structures what gets measured, populate the ledger that governs how each number is calculated, and design the two-tier cadence (MBR and QBR) that schedules when reviews happen and who does what.
In this step, get ready to:
- Build a three-tier metric tree and populate the definition ledger with real Linear data.
- Design the MBR and QBR cadence with n8n automation triggers.
- Produce a RACI that assigns every activity to a named role.
Build the metric tree and populate the ledger
Every number that appears on a review slide must trace back to a definition. The metric tree is the visual map that shows how outcome metrics decompose into delivery metrics, which in turn are predicted by leading indicators.
- Create the metric tree file by running this command from your hold-the-room directory:
touch docs/metric-tree.mmd- Open docs/metric-tree.mmd and paste the following Mermaid diagram:
graph TD
subgraph "Tier 1: Outcomes"
O1[OKR Attainment %]
O2[Portfolio Value Delivered]
O3[Customer Commitments Met]
end
subgraph "Tier 2: Delivery"
D1[Schedule Variance]
D2[Scope Change Rate]
D3[Defect Escape Rate]
D4[Cycle Time]
end
subgraph "Tier 3: Leading Indicators"
L1[Risk Count by Severity]
L2[Dependency Health]
L3[Team Capacity Utilization]
L4[Carry-over Rate]
end
O1 --> D1
O1 --> D2
O2 --> D3
O2 --> D4
O3 --> D1
D1 --> L1
D1 --> L2
D2 --> L3
D2 --> L4
D3 --> L1
D4 --> L2
D4 --> L3What does this metric tree do?
The tree has three tiers, each with a distinct purpose:
- Tier 1 (Outcomes) answers "did we deliver what we promised?" These are scored from the OKR tool in the QBR.
- Tier 2 (Delivery) answers "are programs running on track?" These are the core MBR metrics pulled from Linear Insights.
- Tier 3 (Leading Indicators) answers "what might go wrong next?" These predict trouble before it hits the delivery metrics.
The arrows show causal relationships. When a leading indicator degrades, the delivery metric it feeds will follow.
- Save docs/metric-tree.mmd.
- Verify the diagram renders by pasting it into mermaid.live. You should see three grouped boxes (Outcomes, Delivery, Leading Indicators) with arrows connecting them top-to-bottom.
Diagram not rendering?
- Check that every subgraph block has a matching end keyword.
- Confirm the first line is exactly graph TD with no extra characters.
- Make sure node IDs (like O1, D1, L1) are unique across the entire diagram.
Why isn't my Mermaid metric tree rendering in mermaid.live?
Now you need to populate the ledger so every metric in the tree has a written definition. This is the governance backbone. Without it, the same metric can mean different things to different people.
- Switch to your Google Sheet named "Metric Definition Ledger".
- Open the Definitions tab.
- Populate at least 8 rows, one per metric from your tree. Each row needs all columns filled: Metric ID, Metric Name, Definition, Owner, Source System, Target, Threshold Amber, Threshold Red, Calculation Method, Last Ratified.
Where do I get the metric values?
Four metrics are directly available from Linear Insights: Cycle Time, Lead Time, Issue Count (for velocity), and Scope Change. Open your Linear workspace, navigate to Insights, and pull the values for your active cycle or project.
For the remaining metrics (OKR attainment, schedule variance, defect escape rate, risk count, dependency health, capacity utilization, carry-over rate), use your OKR tool or set realistic targets based on team norms. The owner for each metric must be a named human on your team, not an agent.
Here is an example of how the first few rows should look:
| Metric ID | Metric Name | Definition | Owner | Source System | Target | Threshold Amber | Threshold Red | Calculation Method | Last Ratified |
|-----------|--------------------|-------------------------------------------------------------------|-------------|---------------|--------|-----------------|---------------|----------------------------------------------|---------------|
| M-001 | Cycle Time | Median elapsed time from In Progress to Done for a given cycle | Jane Smith | Linear | 3 days | > 4 days | > 7 days | Median of (Done date - In Progress date) | 2026-07-01 |
| M-002 | Scope Change Rate | % of issues added or removed after cycle start | John Doe | Linear | < 10% | 10-20% | > 20% | (Added + Removed) / Original scope * 100 | 2026-07-01 |
| M-003 | OKR Attainment % | Weighted average of key result completion across portfolio OKRs | Sarah Lee | Quantive | 70% | 50-70% | < 50% | Sum(KR score * weight) / Sum(weights) | 2026-07-01 |Owners are humans, not agents
Per ADR-002 (metric governance), every metric definition is ratified by a human owner. Agents collect and compute. Humans decide what a metric means, what the target is, and whether a threshold change is warranted.
- Confirm each row has a named human in the Owner column.
- Confirm the Source System matches where the agent will actually pull the data (e.g., "Linear" for cycle time, your OKR tool name for attainment).
- Confirm you have at least 8 metrics covering all three tiers of the tree.
Define the two-tier cadence with n8n automation
A review system without a schedule is a one-off meeting. The cadence spec turns this into a standing operating rhythm with clear input deadlines and automated triggers.
- Create the cadence spec file by running:
touch cadence/cadence-spec.md- Open cadence/cadence-spec.md and add the following two-tier specification:
# Cadence Specification
## MBR (Monthly Business Review)
**Audience:** Delivery leadership, program owners
**Purpose:** Are programs on track? What slipped? What is the recovery plan?
**Agenda:**
- Portfolio health summary (5 min)
- Program-by-program status with decisions (15 min)
- Risks and dependencies (5 min)
- Decisions and actions (5 min)
**Input deadline:** Data freeze 2 business days before review
- n8n trigger: notify program owners to finalize status in Linear
**Pre-brief:** Sent 1 business day before review to each decision-maker
- n8n trigger: dispatch pre-brief-drafter agent per stakeholder
**Calendar:** Recurring monthly event in "Executive Review Cadence" calendar
---
## QBR (Quarterly Business Review)
**Audience:** Executive sponsor, finance, steering group
**Purpose:** Outcomes against objectives (scored from OKR tool), portfolio health, strategic decisions
**Agenda:**
- OKR scorecard (5 min)
- Portfolio outcome review (10 min)
- Investment decisions (10 min)
- Forward-looking risks and asks (5 min)
**Input deadline:** Data freeze 5 business days before review
- n8n trigger: freeze data, run metric collection fan-out
**Pre-brief:** Sent 2 business days before review
- n8n trigger: dispatch pre-brief-drafter per stakeholder
**Calendar:** Recurring quarterly event in "Executive Review Cadence" calendarWhat makes this a decision-forcing cadence?
Every agenda section ends with either a decision or an explicit "no decision needed." The MBR forces delivery decisions (recover, descope, escalate). The QBR forces investment decisions (continue, pivot, stop).
The input deadlines ensure data is frozen before the review. No one updates a status mid-meeting to dodge a red light. The pre-briefs ensure no surprises in the room. Decision-makers arrive knowing what they will be asked to decide.
- Save cadence/cadence-spec.md.
Now document the automation layer that makes this cadence repeatable without manual chasing.
- Create the n8n workflow spec by running:
touch cadence/n8n-workflow-spec.md- Open cadence/n8n-workflow-spec.md and add the following trigger specification:
# n8n Workflow Specification
This document defines the automation triggers for the executive review cadence.
Full deployment of the n8n instance (webhook configuration, Claude Code CLI
invocation nodes) is post-session work per the implementation plan.
## Trigger 1: Input Deadline Reached
**Event:** Calendar reminder fires (2 days before MBR, 5 days before QBR)
**Action:** Notify program owners to lock status in Linear
**Channel:** Slack message or email to program-owner distribution list
**Success criteria:** All program statuses marked as "Final" in Linear
## Trigger 2: Data Freeze Confirmed
**Event:** All program owners confirm status is locked
**Action:** Invoke Claude Code metric-collection fan-out
**Detail:** One metric-collector agent per team/project, results written to JSON
**Success criteria:** All collector agents return structured JSON without errors
## Trigger 3: Deck Compiled
**Event:** deck-compiler agent produces final Marp markdown
**Action:** Invoke pre-brief-drafter per stakeholder
**Detail:** Each stakeholder gets a tailored pre-brief based on their profile
**Success criteria:** Pre-brief documents generated and dispatched
## Trigger 4: Review Complete
**Event:** Review meeting ends (manual trigger or calendar event conclusion)
**Action:** Invoke decision-log-keeper to capture decisions
**Detail:** Log all decisions with owner, date, and status into the ledger
**Success criteria:** Decision Log tab updated with at least one entryWhy document the spec instead of deploying n8n now?
The n8n workflow spec is the deliverable for this exercise. Full deployment (webhook configuration, node wiring, credential setup) is Phase 5 work in the implementation plan. Documenting first ensures the logic is correct before spending time on infrastructure plumbing.
- Save cadence/n8n-workflow-spec.md.
- Confirm both files exist by running:
ls cadence/You should see cadence-spec.md and n8n-workflow-spec.md listed.
Produce the RACI
A cadence without accountability is a calendar entry everyone ignores. The RACI assigns exactly one of Responsible, Accountable, Consulted, or Informed to every role for every activity. No unassigned cells means no ambiguity about who does what.
- Create the RACI file by running:
touch cadence/raci.md- Open cadence/raci.md and add the following matrix:
# RACI Matrix
| Activity | Operator/TPM | Program Owners | Engineering Leads | Executive Sponsor | Finance |
|--------------------------------|--------------|----------------|-------------------|-------------------|---------|
| Metric collection | R | C | C | I | I |
| Metric-definition ratification | A | R | C | I | I |
| Narrative drafting | R | C | C | I | I |
| Pre-brief delivery | R | I | I | C | C |
| Deck review | A | R | C | I | I |
| Decision logging | R | C | I | A | I |
| Cadence enforcement | R | C | I | A | I |
| n8n workflow maintenance | R | I | C | I | I |
## Legend
- **R** = Responsible (does the work)
- **A** = Accountable (owns the outcome, one per activity)
- **C** = Consulted (provides input before the work)
- **I** = Informed (notified after the work is done)What does this RACI enforce?
- The Operator/TPM is Responsible for most operational activities (collection, narrative, pre-briefs, logging, cadence, automation).
- Program Owners are Responsible for ratifying their own metric definitions and reviewing their deck sections.
- The Executive Sponsor is Accountable for decisions and cadence enforcement. They own the outcome of showing up and deciding.
- Every cell has exactly one letter. No blanks, no shared accountability.
- Save cadence/raci.md.
- Verify all three cadence files exist by running:
ls cadence/You should see cadence-spec.md, n8n-workflow-spec.md, and raci.md listed.
RACI has blank cells or duplicate letters?
Every cell must have exactly one of R, A, C, or I. If you are unsure who is Accountable for a given activity, ask: "If this fails, whose name is on it?" That person gets the A.
Help me assign the right RACI letter to each role for my executive review activities.
✔️ Awesome, I've got everything!
Great. Double check you have saved all three cadence files plus the metric tree. Your operating rhythm is now fully specified on paper.
ⓧ I'd like to double check the full code
Here is the complete metric tree file:
graph TD
subgraph "Tier 1: Outcomes"
O1[OKR Attainment %]
O2[Portfolio Value Delivered]
O3[Customer Commitments Met]
end
subgraph "Tier 2: Delivery"
D1[Schedule Variance]
D2[Scope Change Rate]
D3[Defect Escape Rate]
D4[Cycle Time]
end
subgraph "Tier 3: Leading Indicators"
L1[Risk Count by Severity]
L2[Dependency Health]
L3[Team Capacity Utilization]
L4[Carry-over Rate]
end
O1 --> D1
O1 --> D2
O2 --> D3
O2 --> D4
O3 --> D1
D1 --> L1
D1 --> L2
D2 --> L3
D2 --> L4
D3 --> L1
D4 --> L2
D4 --> L3Here is the complete cadence spec:
# Cadence Specification
## MBR (Monthly Business Review)
**Audience:** Delivery leadership, program owners
**Purpose:** Are programs on track? What slipped? What is the recovery plan?
**Agenda:**
- Portfolio health summary (5 min)
- Program-by-program status with decisions (15 min)
- Risks and dependencies (5 min)
- Decisions and actions (5 min)
**Input deadline:** Data freeze 2 business days before review
- n8n trigger: notify program owners to finalize status in Linear
**Pre-brief:** Sent 1 business day before review to each decision-maker
- n8n trigger: dispatch pre-brief-drafter agent per stakeholder
**Calendar:** Recurring monthly event in "Executive Review Cadence" calendar
---
## QBR (Quarterly Business Review)
**Audience:** Executive sponsor, finance, steering group
**Purpose:** Outcomes against objectives (scored from OKR tool), portfolio health, strategic decisions
**Agenda:**
- OKR scorecard (5 min)
- Portfolio outcome review (10 min)
- Investment decisions (10 min)
- Forward-looking risks and asks (5 min)
**Input deadline:** Data freeze 5 business days before review
- n8n trigger: freeze data, run metric collection fan-out
**Pre-brief:** Sent 2 business days before review
- n8n trigger: dispatch pre-brief-drafter per stakeholder
**Calendar:** Recurring quarterly event in "Executive Review Cadence" calendarHere is the complete n8n workflow spec:
# n8n Workflow Specification
This document defines the automation triggers for the executive review cadence.
Full deployment of the n8n instance (webhook configuration, Claude Code CLI
invocation nodes) is post-session work per the implementation plan.
## Trigger 1: Input Deadline Reached
**Event:** Calendar reminder fires (2 days before MBR, 5 days before QBR)
**Action:** Notify program owners to lock status in Linear
**Channel:** Slack message or email to program-owner distribution list
**Success criteria:** All program statuses marked as "Final" in Linear
## Trigger 2: Data Freeze Confirmed
**Event:** All program owners confirm status is locked
**Action:** Invoke Claude Code metric-collection fan-out
**Detail:** One metric-collector agent per team/project, results written to JSON
**Success criteria:** All collector agents return structured JSON without errors
## Trigger 3: Deck Compiled
**Event:** deck-compiler agent produces final Marp markdown
**Action:** Invoke pre-brief-drafter per stakeholder
**Detail:** Each stakeholder gets a tailored pre-brief based on their profile
**Success criteria:** Pre-brief documents generated and dispatched
## Trigger 4: Review Complete
**Event:** Review meeting ends (manual trigger or calendar event conclusion)
**Action:** Invoke decision-log-keeper to capture decisions
**Detail:** Log all decisions with owner, date, and status into the ledger
**Success criteria:** Decision Log tab updated with at least one entryHere is the complete RACI:
# RACI Matrix
| Activity | Operator/TPM | Program Owners | Engineering Leads | Executive Sponsor | Finance |
|--------------------------------|--------------|----------------|-------------------|-------------------|---------|
| Metric collection | R | C | C | I | I |
| Metric-definition ratification | A | R | C | I | I |
| Narrative drafting | R | C | C | I | I |
| Pre-brief delivery | R | I | I | C | C |
| Deck review | A | R | C | I | I |
| Decision logging | R | C | I | A | I |
| Cadence enforcement | R | C | I | A | I |
| n8n workflow maintenance | R | I | C | I | I |
## Legend
- **R** = Responsible (does the work)
- **A** = Accountable (owns the outcome, one per activity)
- **C** = Consulted (provides input before the work)
- **I** = Informed (notified after the work is done)Your operating rhythm is fully designed. You have a metric tree that structures measurement, a ledger that governs definitions, a two-tier cadence with input deadlines, four automation triggers, and a RACI with zero blank cells. Next up, you will put this system to work by having your agents assemble the actual review decks.
Assemble the Review Kit
Your operating rhythm is designed. The cadence spec, RACI, and n8n workflow spec define when the reviews happen, who owns what, and what triggers the automation.
Now comes the payoff: the agents actually assemble the review decks. In this step, you will orchestrate a fan-out of metric collectors across your Linear workspace, reconcile every number against the ledger, and produce both the MBR and QBR decks as PDFs. Every metric on every slide will trace to a row in the ledger.
In this step, get ready to:
- Run the metric collection fan-out and reconcile values against the ledger.
- Generate MBR and QBR decks in Marp markdown and compile them to PDF.
- Produce pre-briefs for each decision-making stakeholder and a one-page executive summary.
Run the metric collection fan-out
The metric-collector agent reads data from your Linear workspace. The orchestrator (your main Claude Code session) fans out one collector per team or project, so each returns metrics independently.
- In your Claude Code session, instruct the orchestrator to invoke the metric-collector agent for each team in your Linear workspace.
- Each collector should return structured JSON with four fields: metric_id, value, period, and source_url.
- Tell Claude Code to fan out the collectors in parallel, one per team or project.
What does fan-out mean here?
Fan-out is an orchestration pattern where the main session spawns multiple subagents in parallel, each handling one independent unit of work. In this case, each collector reads data from a different Linear team. They run concurrently and return results to the orchestrator, which merges them into a single dataset.
- Next, instruct Claude Code to invoke the okr-scorer agent to compute attainment % for each outcome metric from your OKR tool (or manual ledger entries if no OKR tool is in use).
- Once all collectors and the OKR scorer have returned, invoke the metric-reconciler agent to cross-check every value against the Definitions tab in your ledger.
What does the reconciler check?
The metric-reconciler compares each collected value against its written definition in the ledger. It checks whether the calculation method matches, whether the source system is correct, and whether the value falls within expected thresholds. Any discrepancy is flagged for your review.
This is the verify-then-merge pattern from ADR-001. Agents collect and compute, but a human ratifies the output before it reaches the narrative.
- Review any metrics flagged by the reconciler.
- For each flagged metric, decide: is the collected value correct per the definition, or does the definition need updating?
- If a definition was stale, update the row in the Definitions tab of your Google Sheet and set a new Last Ratified date.
- Confirm to Claude Code that you have ratified all metrics so the pipeline can proceed.
You are the governance gate
This is the human-in-the-loop step from ADR-002. Agents do not ratify their own output. Your ratification is what makes these numbers defensible when a VP challenges them in the room.
Your reconciled metric set is now ready. Every number has been verified against its written definition and ratified by you.
Generate the MBR and QBR decks
With reconciled metrics in hand, the narrative and compilation agents produce the actual review decks. Honest status is enforced: if a program is amber, it is reported amber with a recovery plan. No false green.
- Instruct Claude Code to invoke the narrative-drafter agent to produce section content for the MBR deck.
- The narrative should include: portfolio health summary with traffic-light status per program, one section per program with key metrics and a decision (or explicit no-decision), top 3 risks by severity, and decisions/actions from the review.
- Then invoke the narrative-drafter again for the QBR deck content: OKR scorecard, portfolio outcome summary (delivered vs. planned), investment decisions (continue/pivot/stop per program), and forward risks.
- Invoke the deck-compiler agent to assemble the MBR narrative into Marp markdown at decks/mbr.md.
- Invoke the deck-compiler again to assemble the QBR narrative into decks/qbr.md.
What goes in the Marp frontmatter?
Each deck starts with Marp frontmatter setting theme: default. Slides are separated by --- (three hyphens on their own line). The MBR title slide reads the date and "Monthly Business Review". The QBR title slide reads the quarter and "Quarterly Business Review".
Every metric on every slide must trace to a row in the Definitions tab. If a figure is uncertain, it must be labeled as an estimate. These are the governance rules from ADR-002.
- Verify that both decks/mbr.md and decks/qbr.md exist and contain valid Marp markdown with the correct frontmatter and slide separators.
- Compile the MBR deck to PDF by running this command:
marp decks/mbr.md -o decks/mbr.pdf- Compile the QBR deck to PDF by running this command:
marp decks/qbr.md -o decks/qbr.pdfHow does Marp convert to PDF?
Marp CLI uses a browser (Chrome, Edge, or Firefox) in the background to render markdown slides and export them as PDF. The -o flag specifies the output path. Because the output filename ends in .pdf, Marp automatically triggers PDF conversion.
- Confirm both PDFs were generated by running:
ls decks/*.pdfYou should see decks/mbr.pdf and decks/qbr.pdf listed in the output.
PDF generation failed?
Marp requires a browser installed on your system for PDF rendering. Make sure Chrome, Edge, or Firefox is installed. If you see a browser connection error, close any running browser instances and try again.
If the command is not found, confirm marp is installed globally by running marp --version.
Help me troubleshoot my Marp PDF compilation error.
- Open one of the PDFs to verify it renders correctly with slides, metrics, and correct formatting.
Generate pre-briefs and the executive summary
Pre-briefs remove surprises from the room so the review can focus on decisions. Each stakeholder gets a tailored document covering what they care about and what they will be asked to decide.
- Instruct Claude Code to invoke the pre-brief-drafter agent for the VP/Sponsor audience. The output should cover: outcomes, investment decisions, and any red items with recommendations. Save it to decks/pre-brief-sponsor.md.
- Invoke the pre-brief-drafter for the Finance audience. The output should cover: budget variance, resource utilization, and ROI metrics. Save it to decks/pre-brief-finance.md.
- Invoke the pre-brief-drafter for Program Owners. The output should cover: their specific program status, decisions they will be asked to make, and what peers are reporting. Save it to decks/pre-brief-program-owners.md.
Why three separate pre-briefs?
A VP cares about outcomes and investment decisions. Finance cares about budget variance and ROI. Program owners care about their own program and what they will be asked to decide. One-size-fits-all briefings bury the signal in noise. Tailored pre-briefs mean each person walks in knowing exactly what to expect.
- Invoke the executive-summary-drafter agent to produce the one-page read-ahead. Save it to decks/executive-summary.md.
- The executive summary should contain: portfolio state in 2 minutes, honest status (no false green), and the three decisions the room will be asked to make.
- Verify all pre-brief and summary files exist by running:
ls decks/pre-brief-*.md decks/executive-summary.mdYou should see four files: pre-brief-sponsor.md, pre-brief-finance.md, pre-brief-program-owners.md, and executive-summary.md.
Missing a pre-brief file?
Check that you instructed Claude Code to save each pre-brief to the decks/ directory with the exact filenames shown above. If a file was saved to a different location, move it to decks/.
Help me find where my pre-brief files were saved.
- Open decks/executive-summary.md and confirm it fits on one page when rendered. A sponsor should be able to read the portfolio state and walk in prepared in under 2 minutes.
Your review kit is assembled. Both decks are compiled to PDF, every metric traces to the ledger, pre-briefs are tailored per stakeholder, and the executive summary gives the sponsor a 2-minute read-ahead. Next up, you will put the system under live pressure with a dispute rehearsal.
Hold the Room
Your review kit is assembled. The MBR and QBR decks are compiled to PDF, every metric traces to a row in the ledger, and each decision-maker has a tailored pre-brief.
Now comes the moment that separates a deck-builder from a Principal TPM. A skeptical VP is going to challenge a headline number in your QBR deck. You need to hold the room on evidence, not opinion, by pulling the written definition from your ledger and walking the calculation live.
In this step, get ready to:
- Run the live dispute rehearsal against your QBR deck.
- Log decisions and produce the two-audience closing readout.
- Confirm the standing cadence and complete the retrospective.
Run the live review with the dispute
The dispute-rehearsal agent plays the role of a skeptical VP. It reads your completed QBR deck and the metric ledger, identifies the most challengeable metric, and disputes it. Your job is to respond with evidence.
Why rehearse a dispute?
In a real executive review, credibility is built or lost in the moment someone challenges a number. If you fumble, the room loses confidence in every other figure in the deck. If you trace the number to its written definition calmly and precisely, the room trusts the entire system.
The dispute-rehearsal agent forces you to practice this skill before it happens with real stakes.
- In your terminal, invoke the dispute-rehearsal agent against your QBR deck and ledger by running:
claude --agent .claude/agents/dispute-rehearsal.mdWhat does this agent do?
The dispute-rehearsal agent reads your decks/qbr.md and the metric ledger. It picks the most challengeable metric based on criteria like large period-over-period change, recently updated definitions, or known data-quality flags.
It then disputes the metric in the voice of a skeptical VP. The challenge will sound something like: "That cycle time number looks cherry-picked. You're measuring from 'In Progress' but half your tickets sit in 'Ready for Dev' for a week before that. Show me the real number."
When the agent presents its challenge, you respond. Do not concede and do not bluff. Follow this exact sequence:
- Pull the metric definition from the Definitions tab in your Google Sheet. Read the Definition, Calculation Method, and Source System columns for the challenged metric.
- Walk the calculation method as written. Explain how the number was computed, citing the source system and the measurement boundaries from the definition.
- Either confirm the figure is correct per the agreed definition, or acknowledge the gap and propose a definition update right there in the room.
- Open the Dispute Record tab in your Google Sheet.
- Add a new row with: Dispute ID (e.g. DR-001), Date, Metric Challenged, Challenger ("VP - Dispute Rehearsal Agent"), Definition Pulled (paste the exact definition text), Calculation Shown (what you walked), Resolution (confirmed or updated), and Logged By (your name).
What does a good resolution look like?
A confirmed resolution means: the definition says X, the data source computes X, the number on the slide matches. The VP's concern was based on a different measurement boundary than the agreed definition.
An updated resolution means: the VP identified a legitimate gap between the definition and what the audience expects. You propose a specific update (e.g., "Change start point from 'In Progress' to 'Ready for Dev'"), note the impact on the metric value, and commit to updating the ledger with a new Last Ratified date.
Stuck on how to respond?
The key is to never argue from memory. Always pull the written definition first. If the definition supports your number, say so and cite it. If it does not, acknowledge the gap immediately. Bluffing erodes trust faster than admitting a measurement needs tightening.
help me respond to this VP challenge on my metric
Log decisions and produce the two-audience closing readout
Every executive review ends with decisions. Decisions without a written record are decisions that never happened. The decision-log-keeper agent captures what was decided, who owns it, and when it is due.
- Invoke the decision-log-keeper agent to record the review outcomes:
claude --agent .claude/agents/decision-log-keeper.mdWhat gets logged?
The decision-log-keeper records every decision from the review into the Decision Log tab. Each entry gets a Decision ID, Date, Review Type (QBR), the decision itself, an owner, a due date, and a status (open/closed).
The dispute resolution counts as a decision. If you confirmed the metric, the decision is "Metric definition confirmed as-is." If you proposed an update, the decision is the specific update with a due date.
- Open the Decision Log tab in your Google Sheet.
- Verify the agent populated at least one row with all columns filled: Decision ID, Date, Review Type, Decision, Owner, Due Date, Status.
- If any fields are missing or incorrect, update them manually. The operator ratifies the log, not the agent.
Now produce the two-audience closing readout. Different audiences need different frames of the same system.
Why two readouts?
Delivery leadership needs to know how the system works so they can operate it. The executive sponsor needs to know what governance capability the organization now has and what it proves. Same system, different lenses.
- Create docs/readout-delivery.md for delivery leadership and program owners. Include these sections:
- What was built: the standing system, the agent roster, the automation.
- How it runs: cadence, input deadlines, n8n triggers.
- What broke during the build and what was fixed.
- Lessons learned for the next cycle.
- Create docs/readout-executive.md for the executive sponsor and steering group. Include these sections:
- What governance capability the organization now has.
- The proof: the live dispute was reconciled from the ledger and the decision is logged.
- The 90-day adoption path: Day 1 first MBR on schedule, Day 30 cadence standing, Day 90 QBR runs and ledger accepted as source of truth.
- The leadership dependency: the system enables governance but does not guarantee it. Leadership must attend and decide.
Let the agents draft first
You can use Claude Code to draft both readout documents based on the artifacts you have produced. Review and revise what it generates. The operator's voice matters here because these documents carry your credibility.
- Save both readout files in the docs/ directory.
- Confirm the delivery readout names specific breakages and fixes from your build process.
- Confirm the executive readout references the dispute by metric name and states the resolution.
Not sure what broke during the build?
Think back to Step 4 when the metric-reconciler flagged discrepancies. Did any metric definition need updating? Did the narrative-drafter produce a false green that you corrected? Those are your "what broke" examples.
help me identify what broke during my build
Retrospective and standing cadence confirmation
The system is only valuable if it repeats. This substep locks the cadence into place and documents what to improve for the next cycle.
- Create docs/retro.md with the following sections:
# Retrospective
## What Worked
<!-- Which agents produced accurate output with minimal operator correction? -->
<!-- Which parts of the cadence spec ran smoothly? -->
## What Broke
<!-- Where did a metric definition not match the actual data source? -->
<!-- Where did the pre-brief miss something the VP cared about? -->
<!-- Where did the narrative-drafter produce status that needed correction? -->
## Standing Improvements
<!-- What definitions need tightening? -->
<!-- What agent prompts need tuning? -->
<!-- What cadence timing needs adjusting? -->
## Proof of Work
The operator held the room on a disputed metric by tracing it to the ledger.
The decision is logged. The cadence is set. The system repeats.What goes in each section?
"What worked" names the agents and processes that ran cleanly. "What broke" names specific failures (a definition that did not match, a pre-brief that missed a stakeholder concern). "Standing improvements" turns those failures into actions for the next cycle.
The "Proof of work" statement is the governance anchor: you survived the dispute, logged the decision, and set the cadence. That is the deliverable.
- Fill in each section of docs/retro.md with specifics from your build. Replace the comments with real observations.
- Save the file.
Now confirm the standing cadence is locked in and ready to run on Day 1.
- Open cadence/cadence-spec.md and add the next MBR date and next QBR date at the bottom of the file.
- Switch to your Executive Review Cadence Google Calendar and verify the next MBR and QBR events are visible with input-deadline reminders.
- Open cadence/n8n-workflow-spec.md and confirm all four triggers are documented (input deadline, data freeze, deck compiled, review complete). Add a note at the top: "Ready for deployment."
- Share the Google Sheet (Metric Definition Ledger) with the owners listed in your RACI. Each metric owner needs edit access to their metrics. The TPM (you) retains admin access.
Why share the ledger now?
A metric definition without a reachable owner is a metric definition that rots. By sharing the ledger with each owner in the RACI, you ensure definitions stay current. When a target changes or a calculation method evolves, the owner updates the ledger and the Last Ratified date.
- Save all updated files (cadence/cadence-spec.md and cadence/n8n-workflow-spec.md).
- Confirm the Google Sheet sharing dialog shows the correct owners with edit access.
Not sure what dates to set?
Pick the first business day of next month for the MBR. Pick the last full week of the current quarter for the QBR. The exact dates matter less than the act of committing to them. A date in the calendar is a promise.
help me pick review dates
Secret mission
The Pre-Mortem Agent
Your dispute-rehearsal agent waits for a challenge and reacts. But a Principal TPM does not walk in hoping nothing blows up. Add a pre-mortem agent that scans the deck before every review, identifies the three metrics most likely to be disputed, and pre-writes the reconciliation path for each. Shift from reactive defense to proactive inoculation.
Clean Up Your Resources
Clean Up Your Resources
Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs on free-tier and flat-rate tools, so there are no ongoing metered costs.
Resources you created:
- Google Sheet (Metric Definition Ledger): free, persistent, no cost.
- Google Calendar (Executive Review Cadence): free, persistent, no cost.
- Local project directory (hold-the-room/): agent definitions, decks, docs, cadence specs.
- n8n workflow spec: documented for deployment. n8n self-hosted is free. n8n Cloud free trial is available.
- Claude Code usage: covered by Claude Max subscription at a flat rate.
Keep everything running
No action needed. Choose this if you plan to run the MBR monthly and the QBR quarterly against real program data.
- The cadence is designed to repeat. Your Google Calendar events fire on schedule and input-deadline reminders arrive automatically.
- Deploy the n8n workflow from cadence/n8n-workflow-spec.md to make the review assembly hands-free.
- Keep iterating on agent prompts in .claude/agents/ as you learn what works in live reviews.
- Your metric ledger stays the single source of truth. Update definitions as your team's norms evolve.
Pause - I'll come back to this later
The system is dormant until the next scheduled review. No ongoing cost accumulates while paused.
- Dismiss or snooze the recurring Google Calendar reminders so they stop notifying you until you are ready to resume.
- Your Google Sheet (Metric Definition Ledger) remains accessible in Google Drive at no cost.
- Your local hold-the-room/ directory stays on disk. No running processes to stop.
- When you are ready to resume, reactivate the calendar events and run the metric-collection fan-out against fresh Linear data.
Delete - I don't want to use this again
Remove all project resources and start fresh. Follow each item below to clean up completely.
- Delete the Google Sheet: open Google Drive, right-click the Metric Definition Ledger file, and select Move to trash.
- Delete the Google Calendar: open Google Calendar, click the three-dot menu next to Executive Review Cadence in the left sidebar, select Settings and sharing, scroll to the bottom, and click Delete.
- Delete the local project directory. On macOS or Linux, run:
cd ~/Desktop
rm -rf hold-the-roomOn Windows, run:
cd ~\Desktop
rmdir /s /q hold-the-room- Confirm deletion by running:
ls ~/Desktop | grep hold-the-roomYou should see no output. The directory is gone.
- If you exported the MBR and QBR PDFs elsewhere (email, shared drive), delete those copies as well.
Nice Work!
Nice Work!
You just built a complete executive review operating system powered by a swarm of Claude agents. Every number in your decks traces to a single source of truth, and you proved it under live pressure by holding the room on a disputed metric.
You've learned how to:
- Build a standing MBR and QBR review system assembled by 10+ Claude Code agents using fan-out, pipeline, and verify-then-merge orchestration patterns on flat-rate and free-tier tooling.
- Create a metric-definition ledger as the single source of truth and design a two-tier cadence with pre-briefs, input deadlines, n8n automation triggers, a Google Calendar schedule, and a complete RACI.
- Survive a live dispute reconciliation where a skeptical VP challenged a headline number, trace the metric to its written definition in the ledger, reconcile it on the spot, and log the decision as governance proof.
- (Secret Mission) Add a pre-mortem agent that identifies vulnerable metrics before each review and pre-writes the reconciliation path, shifting from reactive defense to proactive inoculation.
Ready to quiz yourself?