@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/outlook/references/auth.md

@@ -0,0 +1,118 @@
+# Outlook Auth Reference
+
+## Vendored upstream
+
+The PKCE flow and encrypted token store are adapted from:
+
+- **Repo:** [`nsakki55/outlook-mcp`](https://github.com/nsakki55/outlook-mcp)
+- **Pinned commit:** `e49d8e68ac8d69db653c25803127dc3b98626cda`
+- **License:** MIT
+
+Adaptations:
+
+- Per-account paths (`{ACCOUNTS_DIR}/{accountId}/secrets/outlook/`) instead of upstream's single-user `~/.outlook-mcp/`
+- `keytar` fallback removed (Pi runs headless; no Secret Service)
+- `node-persist` removed; single JSON blob written atomically (temp + rename)
+- Loopback callback port is **ephemeral** via `server.listen(0)` (upstream uses fixed `49152`)
+- No `xdg-open` browser auto-launch; auth URL is logged + returned to the operator for the VNC browser
+- `outlook-account-register` awaits the full PKCE flow synchronously (5-min timeout)
+
+To re-vendor at a newer SHA:
+
+1. Fetch `tokenManager.ts` and `authManager.ts` from the new SHA.
+2. Apply the adaptations above.
+3. Update the **Pinned commit** line above.
+4. Bump `@maxy/outlook` version.
+5. Run the test suite.
+
+## Entra app registration (one-time per Maxy install)
+
+The plugin requires an Azure AD ("Entra ID") app the operator owns. Steps:
+
+1. Sign in to the [Azure portal](https://portal.azure.com) with a Microsoft account.
+2. Go to **Microsoft Entra ID → App registrations → New registration**.
+3. **Name:** `Maxy Outlook` (or any name the operator prefers).
+4. **Supported account types:** *Accounts in any organizational directory and personal Microsoft accounts*.
+5. **Redirect URI** (Platform: *Mobile and desktop applications*): `http://localhost`
+   - **Note:** no port is specified. Microsoft Identity Platform treats native-app loopback redirects with port-flexible matching, allowing the plugin to use an ephemeral port.
+6. Click **Register**. Copy the **Application (client) ID** — this is `OUTLOOK_CLIENT_ID`.
+7. Go to **API permissions → Add a permission → Microsoft Graph → Delegated permissions**, add:
+   - `offline_access`
+   - `User.Read`
+   - `Mail.Read`
+   - `Calendars.Read`
+   - `Contacts.Read`
+8. Click **Grant admin consent for <tenant>** if applicable. Personal accounts auto-consent at first sign-in.
+9. Set the env var on the Pi:
+   ```
+   OUTLOOK_CLIENT_ID=<the Application (client) ID copied above>
+   OUTLOOK_TENANT_ID=common   # or your tenant GUID for single-tenant
+   ```
+
+## PKCE flow (per-account)
+
+Triggered by `outlook-account-register`. Sequence:
+
+```
+operator                                        plugin                              Microsoft
+   |                                              |                                     |
+   | outlook-account-register                     |                                     |
+   |--------------------------------------------->|                                     |
+   |                                              | bind 127.0.0.1:<ephemeral-port>     |
+   |                                              | generate code_verifier (32 bytes)   |
+   |                                              | code_challenge = SHA256(verifier)   |
+   |                                              | state = randomBytes(16)             |
+   |                                              |                                     |
+   | { authUrl, status: "pending" }               |                                     |
+   |<---------------------------------------------|                                     |
+   |                                              |                                     |
+   | open authUrl in VNC browser                  |                                     |
+   |--------------------------------------------------------------------------------->  |
+   |                                              |                                     |
+   |                                  consent ←--------------------------------------- |
+   |                                              |                                     |
+   |                                              | GET /callback?code=...&state=...   |
+   |                                              | <----------------------------------|
+   |                                              |                                     |
+   |                                              | verify state                        |
+   |                                              | POST /token (code + verifier)       |
+   |                                              | -----------------------------------> |
+   |                                              | < tokens                             |
+   |                                              | <----------------------------------- |
+   |                                              | encrypt → write {tokens.enc}         |
+   |                                              | GET /me  (record graphUserId)        |
+   |                                              | -----------------------------------> |
+   |                                              |                                     |
+   | { status: "registered", graphUserId, ... }   |                                     |
+   |<---------------------------------------------|                                     |
+```
+
+## Token store layout
+
+Per-account, mode 0700 directory + mode 0600 files:
+
+```
+data/accounts/<accountId>/secrets/outlook/
+├── .key          # 32 random bytes, base64-encoded — the AES-256-CBC key
+└── tokens.enc    # AES-256-CBC ciphertext: "<iv-hex>:<cipher-hex>" of JSON blob
+```
+
+The JSON blob shape:
+
+```typescript
+{
+  accessToken: string;
+  refreshToken: string | null;
+  accessTokenExpiry: number;        // unix ms
+  refreshTokenExpiry: number;       // unix ms; ~90 days from issue
+  lastRefresh: number;              // unix ms
+  graphUserId: string | null;       // from /me.id
+  scopes: string[];                 // granted scopes from token response
+}
+```
+
+Atomic write: temp + rename. Either old or new tokens, never partial.
+
+## Refresh
+
+Triggered automatically when the access token is within `5 minutes` of expiry (`refreshThresholdMs`). Failure → terminal `token-refresh-failed`, tokens cleared, operator must re-register. Refresh tokens last 90 days.

package/payload/platform/plugins/outlook/references/graph-surfaces.md

@@ -0,0 +1,114 @@
+# Graph Surfaces
+
+Microsoft Graph endpoints used by each tool, with the response shape and the fields selected.
+
+## outlook-mail-list
+
+**Endpoint (Inbox):** `GET /me/mailFolders/Inbox/messages?$top={N}&$orderby=receivedDateTime DESC&$select=id,subject,from,receivedDateTime,bodyPreview,isRead`
+
+**Endpoint (other folder):** `GET /me/mailFolders/{folderId-or-displayName}/messages?...`
+
+**Returned shape:**
+```typescript
+Array<{
+  id: string;
+  subject: string | null;
+  from: string | null;          // emailAddress.address
+  receivedDateTime: string;     // ISO 8601
+  bodyPreview: string;          // truncated to 1024 chars
+  isRead: boolean;
+}>
+```
+
+## outlook-mail-search
+
+**Endpoint:** `GET /me/messages?$search="{query}"&$top={N}&$select=id,subject,from,receivedDateTime,bodyPreview,isRead`
+
+**Required header:** `ConsistencyLevel: eventual` (Graph requirement for `$search`).
+
+**Returned shape:** identical to `outlook-mail-list`.
+
+## outlook-calendar-list
+
+**Endpoint:** `GET /me/calendarView?startDateTime={now}&endDateTime={now+rangeDays}&$top={N}&$orderby=start/dateTime ASC&$select=id,subject,start,end,location,attendees,isAllDay,organizer`
+
+**Returned shape:**
+```typescript
+Array<{
+  id: string;
+  subject: string | null;
+  start: { dateTime: string; timeZone: string };
+  end:   { dateTime: string; timeZone: string };
+  location: string | null;
+  attendees: Array<{ email: string; name: string | null; response: string }>;
+  isAllDay: boolean;
+  organizer: string | null;
+}>
+```
+
+## outlook-calendar-event
+
+**Endpoint:** `GET /me/events/{eventId}?$select=id,subject,start,end,location,attendees,isAllDay,organizer,bodyPreview,body,webLink`
+
+**Returned shape:** as `outlook-calendar-list` plus:
+```typescript
+{
+  bodyPreview: string;       // 1024 chars
+  body: string;              // up to 16384 chars (HTML or text per content type)
+  webLink: string | null;
+}
+```
+
+## outlook-contacts-list
+
+**Endpoint:** `GET /me/contacts?$top={N}&$select=id,displayName,emailAddresses,businessPhones,homePhones,mobilePhone,jobTitle,companyName`
+
+**Returned shape:**
+```typescript
+Array<{
+  id: string;
+  displayName: string | null;
+  emailAddresses: string[];   // .address values flattened
+  phones: string[];           // business + home + mobile concatenated
+  jobTitle: string | null;
+  companyName: string | null;
+}>
+```
+
+## outlook-mailbox-info
+
+**Endpoint:** `GET /me/mailFolders?$top=50&$select=id` (best-effort — folder count is null if Graph is unreachable)
+
+**Returned shape:**
+```typescript
+{
+  registered: boolean;
+  graphUserId: string | null;
+  scopes: string[];
+  tokenExpSec: number | null;
+  refreshTokenExpSec: number | null;
+  tokenWithinRefreshWindow: boolean;
+  folderCount: number | null;
+}
+```
+
+## outlook-account-register
+
+No Graph endpoint of its own. The flow exchanges an authorization code at:
+
+- `POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`
+
+After the token exchange, the tool fetches `GET /me?$select=id,mail,userPrincipalName` to record `graphUserId`.
+
+## Error classification
+
+All tool failures route through `lib/graph-client.ts:classifyGraphError`. Decisions key off **status code + Graph `error.code` field + headers**, never the error `message` body.
+
+| HTTP status | Graph `error.code` | Class | Action |
+|---|---|---|---|
+| 401 | (any) | `auth` | Refresh once, retry; if still 401 → terminal `auth-required` |
+| 429 | (any) — header `Retry-After` present | `rate-limit-recoverable` | Backoff per header, retry once |
+| 429 | (any) — header `Retry-After` absent | `rate-limit-terminal` | Terminal abort |
+| 503 | `MailboxNotEnabledForRESTAPI` | `on-prem` | Terminal: route operator to IMAP plugin |
+| 5xx | (any) | `5xx` | Retry once with 500 ms; then terminal |
+| any | (any) | `other` | Re-throw |

package/payload/platform/plugins/outlook/skills/outlook/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: outlook
+description: "Microsoft 365 / Outlook.com via Microsoft Graph (read-only). Use when the user asks about their Outlook mail, calendar, or contacts — listing, searching, or checking events. First-time use requires outlook-account-register; subsequent use is transparent. Tools — outlook-mail-list / outlook-mail-search (inbox), outlook-calendar-list / outlook-calendar-event (calendar), outlook-contacts-list (contacts), outlook-mailbox-info (health), outlook-account-register (PKCE register)."
+---
+
+# Outlook (Microsoft Graph)
+
+Read-only access to the user's Outlook.com or Microsoft 365 mailbox via Microsoft Graph. Per-account OAuth, encrypted token storage, refresh handled automatically.
+
+## When to activate
+
+Activate when the user asks about:
+
+- Their Outlook / Office 365 / Hotmail mail (recent messages, search by keyword/sender)
+- Their Outlook calendar (upcoming events, specific event details, free/busy windows)
+- Their Outlook contacts
+
+Do **not** activate for:
+
+- IMAP-only providers (Gmail, iCloud, custom domains not on Microsoft 365) — use the `email` plugin instead.
+- On-premises Exchange — Microsoft Graph deprecated hybrid REST 2023-07. The plugin detects on-prem mailboxes and emits a clear error pointing to the IMAP path.
+- Sending / drafting / modifying messages or events — out of scope. Read-only.
+
+## First-time setup (one-time per account)
+
+The Outlook plugin needs an **Entra app registration** in the operator's Microsoft tenant. This is a one-time-per-install step (not per-account), documented at [`references/auth.md`](references/auth.md).
+
+Once the Entra app exists and `OUTLOOK_CLIENT_ID` is set in the Maxy installation, run:
+
+1. **`outlook-account-register`** — the tool returns an `authUrl`. The operator opens this URL in the VNC browser, signs in with the Microsoft account they want to connect, and consents to the requested scopes (`offline_access`, `User.Read`, `Mail.Read`, `Calendars.Read`, `Contacts.Read`).
+2. Tool returns `{ status: "registered", graphUserId, scopes, tokenExpSec }` once consent completes.
+
+Subsequent tool calls use the persisted refresh token to mint access tokens transparently. Re-register is only needed if the refresh token expires (90 days) or the user revokes consent.
+
+## Reading mail
+
+- `outlook-mail-list` — recent mail, default top=25, folder=Inbox.
+- `outlook-mail-search query=<keyword>` — Microsoft Graph `$search` over the mailbox.
+
+## Reading calendar
+
+- `outlook-calendar-list rangeDays=<N>` — events in the next N days (default 7, max 365).
+- `outlook-calendar-event eventId=<id>` — single event with full body and attendees.
+
+## Reading contacts
+
+- `outlook-contacts-list` — top contacts, default top=50.
+
+## Health check
+
+- `outlook-mailbox-info` — quick state probe: is the account registered? Are tokens within the refresh window? How many folders are visible? Useful when troubleshooting a tool that returned `auth-required`.
+
+## What can go wrong
+
+| Error | Meaning | Operator action |
+|---|---|---|
+| `auth-required` | Account not registered, or refresh token expired | Run `outlook-account-register` |
+| `Outlook token refresh failed` | Network down or refresh token invalidated | Verify connectivity; re-run register if persistent |
+| `Microsoft Graph does not support on-premises Exchange` | Mailbox is on hybrid Exchange | Use the `email` plugin (IMAP) |
+| `Outlook rate-limited without Retry-After hint` | Graph 429 with no backoff guidance | Retry later; if persistent, file a bug |
+
+## Reference files
+
+- [`references/auth.md`](references/auth.md) — Entra app registration + PKCE flow + re-vendor procedure
+- [`references/graph-surfaces.md`](references/graph-surfaces.md) — Graph endpoint and response shape per tool

package/payload/platform/plugins/projects/PLUGIN.md

@@ -0,0 +1,90 @@
+---
+name: projects
+description: "Structured project execution. Phased sprints, operational investigations, deliverable reviews, and retrospectives — backed by :Project:Task graph nodes with HAS_TASK relationships, health signals, and lifecycle tracking."
+requires:
+  - tasks
+metadata: {"platform":{"always":false,"embed":["admin"],"pluginKey":"projects","optional":true,"recommended":true}}
+---
+
+# Projects
+
+Structured execution discipline for business work. When the user has a project — a kitchen refit, a client engagement, a product launch, an operational investigation — this plugin provides phased workflows backed by dedicated project tools that handle graph operations atomically.
+
+## When to Apply
+
+When the user describes work that involves multiple steps, dependencies, or deliverables, offer structured execution. Ask: "Would you like to run this as a structured project, or just handle it as a task?" Learn the user's preference over time — if they consistently choose one mode, stop asking and default to it.
+
+Explicit triggers always apply structured execution without asking:
+- "let's sprint on..."
+- "run a project on..."
+- "investigate why..."
+- "review the deliverables for..."
+- "let's do a retro on..."
+
+## Modes
+
+| Mode | When | Reference |
+|------|------|-----------|
+| Sprint | Multi-step project execution with deliverables | `references/sprint.md` |
+| Investigation | Operational problem that needs root-cause diagnosis | `references/investigation.md` |
+| Review | Deliverable ready for quality check against the brief | `references/review.md` |
+| Retrospective | Project completed, extract learnings for future work | `references/retrospective.md` |
+
+Load the relevant reference via `plugin-read` when entering a mode. Each reference describes outcomes and constraints for that mode — follow them.
+
+## Creating a Project
+
+Use `project-create` to create a project atomically. One tool call creates the parent `:Project:Task` node, all child work items, dependency relationships (`BLOCKS`), and entity relationships (`RAISED_BY`, `AFFECTS`) in a single transaction.
+
+Choose a tier based on scope:
+- **quick** — straightforward work, few steps (e.g., boiler install)
+- **standard** — moderate complexity, multiple phases (e.g., kitchen refit)
+- **full** — significant scope, many dependencies (e.g., new build project)
+
+Include work items with their dependencies when the scope is known. If the user describes work incrementally, create the project first and add tasks later via `task-create` + `task-relate`.
+
+## Checking Project Status
+
+Use `project-list` to see all active projects with health signals. Use `project-get` for detailed status on a specific project including children, blockers, and lifecycle history.
+
+Health signals are computed server-side from child task data:
+
+| Signal | Meaning |
+|--------|---------|
+| Green | On track — no overdue tasks, no unresolved blockers |
+| Amber | Warning — at least one overdue task or blocker |
+| Red | At risk — multiple overdue, critical blocker, or stale |
+| Grey | No due dates set — shows completion count only |
+
+## Updating a Project
+
+Use `project-update` to change phase, tier, target date, client reference, status, or append notes. Phase changes automatically record `[PROJECT:PHASE]` lifecycle notes — no need to pass a separate note for transitions.
+
+## Completing a Project
+
+Use `project-complete` to mark a project done. The tool returns any incomplete children so you can confirm with the user: "2 tasks are still pending: X and Y. Mark them as cancelled and complete the project?" The tool always completes — it informs rather than gates.
+
+## Session-Start Awareness
+
+Active project summaries are injected into the session context automatically. At session start, project health data (name, phase, signal, next action) appears in the `<previous-context>` block without any tool calls needed.
+
+When project context is present, surface it conversationally: "You have 2 active projects. The kitchen refit is on track (3 of 5 done). The boiler install is blocked — waiting on parts."
+
+## Structured Lifecycle Notes
+
+The project tools append structured notes to the project node at key lifecycle moments. These create a searchable audit trail consumed by the retrospective to reconstruct project timelines.
+
+| Event | Note format |
+|-------|-------------|
+| Project start | `[PROJECT:START] {name} — {tier} tier, {n} tasks planned` |
+| Phase transition | `[PROJECT:PHASE] {phase name} — {brief summary of outcome}` |
+| Scope change | `[PROJECT:CHANGE] {what changed} — Reason: {why}` |
+| Issue recorded | `[PROJECT:ISSUE] {description} — Impact: {assessment}` |
+| Project complete | `[PROJECT:COMPLETE] {name} — {done}/{total} tasks done, {n} deferred` |
+| Project abandoned | `[PROJECT:ABANDONED] {name} — Reason: {why}` |
+
+For scope changes and issues, use `project-update` with a `note` parameter following the format above.
+
+## Dependencies
+
+This plugin requires the `tasks` plugin to be enabled. Project tools are co-located in the tasks MCP server — same data domain, same Neo4j connection. If task tools are unavailable (tasks plugin not enabled), tell the user: "I need the tasks plugin to run structured projects. Would you like to enable it?" Do not attempt structured execution without task tools — fall back to a regular conversational approach until the dependency is resolved.

package/payload/platform/plugins/projects/references/investigation.md

@@ -0,0 +1,63 @@
+# Investigation
+
+Root-cause diagnosis for operational problems. When something is going wrong — customer complaints spiking, a process is failing, costs are running over, a system isn't working as expected — this mode applies disciplined investigation to find the actual cause before proposing fixes.
+
+The iron rule: **no fixes without root cause.** Speculative fixes mask problems and waste time. One measurement beats three guesses.
+
+## Phases
+
+### Investigate
+
+Gather evidence about the problem. What is actually happening? What should be happening? When did the gap appear?
+
+- Search memory for relevant history — prior incidents, related changes, affected entities
+- Check task history for recent work that may be related
+- Ask the user targeted questions to establish the timeline and scope
+- Create a Task for this investigation with `[PROJECT:START] Investigation: {problem description}`
+
+Record what you find in the investigation task notes — every data point, every observation.
+
+### Analyse
+
+Pattern-match the evidence. What does the data tell you?
+
+- Look for correlations: did the problem start when something changed?
+- Check for scope: is this one instance or a pattern? One customer or many?
+- Test assumptions: is what the user believes about the problem supported by evidence?
+- Identify what you don't know and what evidence would fill the gap
+
+Record the analysis in task notes: `[PROJECT:PHASE] Analysis — {key findings}`.
+
+### Hypothesise
+
+Form one or more hypotheses that explain the evidence. For each:
+
+- **Hypothesis:** What do you believe is the cause?
+- **Evidence for:** What observations support this?
+- **Evidence against:** What observations contradict this?
+- **Test:** What would confirm or disprove this hypothesis?
+
+Rank hypotheses by how well they explain ALL the evidence, not just part of it. Present them to the user with a recommendation.
+
+### Implement
+
+Once the root cause is confirmed (or the most likely hypothesis is agreed), propose and execute the fix:
+
+- Describe the fix and its expected effect
+- Identify any risks or side effects
+- Execute the fix
+- Verify the problem is resolved — check the same evidence that surfaced the problem
+
+Mark the investigation complete: `[PROJECT:COMPLETE] Investigation: {problem} — Root cause: {cause}, Fix: {what was done}`.
+
+If the fix reveals a deeper problem, create a new investigation task rather than expanding this one.
+
+## When to Use
+
+- "Why are we getting so many complaints about..."
+- "Something is wrong with the scheduling..."
+- "Costs are way over what we quoted..."
+- "The process isn't working..."
+- "I keep seeing the same problem with..."
+
+Do not use investigation mode for simple questions with obvious answers. If the user asks "why did invoice X fail?" and the answer is immediately clear from the data, just answer. Investigation mode is for problems that need digging.

package/payload/platform/plugins/projects/references/retrospective.md

@@ -0,0 +1,71 @@
+# Retrospective
+
+Extract operational knowledge from a completed project. The goal is to accumulate institutional learning that makes future projects better — shorter timelines, fewer surprises, better estimates, stronger processes.
+
+This is not a performance review. It's a knowledge extraction exercise. The focus is on what was surprising, what assumptions were wrong, and what the business now knows that it didn't know before.
+
+## Process
+
+### Reconstruct the Timeline
+
+Read the project's Task node and its notes. The structured lifecycle notes (`[PROJECT:START]`, `[PROJECT:PHASE]`, `[PROJECT:COMPLETE]`) provide the skeleton. Fill in the timeline:
+
+- When did each phase start and end?
+- Where were the delays? What caused them?
+- What went faster than expected? Why?
+- Were the original estimates accurate? If not, by how much and in which direction?
+
+### Identify Learnings
+
+For each phase of the project, ask:
+
+- **What was surprising?** — anything that didn't match expectations, positively or negatively
+- **What assumption was wrong?** — beliefs that were disproved by reality (e.g., "materials take 2 weeks" when they actually took 3)
+- **What would you do differently?** — concrete changes to approach, process, or tools
+- **What worked well?** — approaches worth repeating on future similar projects
+
+Focus on learnings that are transferable to future projects, not one-off observations about this specific project.
+
+### Persist Learnings
+
+For each actionable learning, write it to the graph so it can be surfaced on future similar projects:
+
+Use `memory-write` to create an entity with:
+- **labels:** `["DefinedTerm"]`
+- **properties:**
+  - `name`: Short description of the learning (e.g., "Kitchen refit material lead times")
+  - `description`: Full learning with context (e.g., "Materials for a kitchen refit consistently take 3 weeks, not 2. Factor in supplier delays and partial deliveries. Always confirm lead times directly with the supplier rather than relying on catalogue estimates.")
+  - `category`: `"project-learning"`
+- **relationships:** `[{ targetId: "{project task ID}", type: "ABOUT" }]`
+
+The `ABOUT` relationship links the learning to the source project. The embedding on the entity enables `memory-search` to surface it when a future project has a similar description.
+
+### Present the Summary
+
+Summarise the retrospective for the user:
+
+- **Project:** Name and duration
+- **Outcome:** Completed/partial/abandoned, with task completion stats
+- **Key learnings:** The 3-5 most important things learned, each in one sentence
+- **Applied to graph:** How many learnings were persisted and what they cover
+- **Recommendation:** One concrete action for the next similar project
+
+Mark the retrospective complete: `[PROJECT:PHASE] Retrospective — {n} learnings captured`.
+
+## Cross-Project Learning
+
+When starting a new project, `memory-search` with the project description will surface relevant learnings from past projects (because learnings are DefinedTerm entities with embeddings). Present these to the user during the Plan phase:
+
+"Based on past projects, here's what I've learned that might be relevant:
+- {learning 1} (from {source project})
+- {learning 2} (from {source project})"
+
+The user decides whether to act on prior learnings. They are inputs to planning, not constraints.
+
+## When to Use
+
+- After a project sprint completes (the Learnings phase of a Full tier sprint loads this reference)
+- "What did we learn from the Henderson project?"
+- "Let's do a retro on the kitchen refit"
+- "Before we start the next one, what should we keep in mind?"
+- On request at any time for any completed project

package/payload/platform/plugins/projects/references/review.md

@@ -0,0 +1,51 @@
+# Deliverable Review
+
+Quality review of completed work against the original brief. When a project has produced deliverables and someone needs to confirm they meet the standard before handoff, sign-off, or client delivery.
+
+This is not a progress check — it's a quality gate. The work should be substantially complete before entering review mode.
+
+## Process
+
+### Establish the Brief
+
+Retrieve the original brief, spec, or agreement that defines what was promised. This may be:
+- The locked execution plan from a sprint (if the work came from a structured project)
+- A quote or proposal sent to a client
+- A verbal agreement captured in task notes or memory
+- A regulatory requirement or compliance checklist
+
+If no written brief exists, construct one from the available evidence and confirm it with the user before proceeding.
+
+### Review Each Deliverable
+
+For every item in the brief:
+
+- **Delivered as promised** — the deliverable meets the agreed specification. State what confirms this.
+- **Delivered with deviation** — the deliverable exists but differs from what was agreed. Describe the difference and whether it's acceptable.
+- **Not delivered** — the deliverable is missing. Determine whether it was intentionally deferred, forgotten, or blocked.
+- **Over-delivered** — work was done beyond what was promised. Note whether this adds value or represents scope creep.
+
+### Quality Assessment
+
+Beyond checking against the brief, assess overall quality:
+- Is the work client-ready? Would you be comfortable handing this to the end recipient?
+- Are there obvious errors, omissions, or rough edges?
+- Does the work reflect the agreed standard of care for this type of deliverable?
+- If this work will be built upon later, is the foundation solid?
+
+### Verdict
+
+Summarise the review:
+- **Pass** — all deliverables meet the brief, quality is acceptable. Ready for handoff.
+- **Conditional pass** — most deliverables meet the brief, but specific items need attention before handoff. List them.
+- **Fail** — significant gaps between what was promised and what was delivered. List every gap and what's needed to resolve it.
+
+Record the verdict in the project task notes: `[PROJECT:PHASE] Review — {Pass/Conditional/Fail}: {summary}`.
+
+## When to Use
+
+- "Can you check the documents before I send them to the client?"
+- "Review the quote package for the Henderson project"
+- "Is everything ready for handoff?"
+- "Check if we've done everything we promised"
+- "The work is done — review it against the original spec"