Opulent OS Heavy — Get Started

Guide Structure: Writing & Visual Best Practices

Show work, not chrome. Pair every claim with an artifact (diff, SQL, chart) and a 1-line 'why it's correct.' Captions must cite the evidence (file/line/test/run link).

When Heavy Shines

Best yield: tasks an engineer can do in a few hours with clear acceptance.

Deploy Heavy for multi-stage tasks that need tools and deliver tangible outputs:

Ideal Scenarios:

• Targeted code refactors
• CI/CD debugging and migrations (e.g., Jenkins → GitHub Actions)
• Automated PR reviews with contextual analysis
• Cited research briefs
• Automated reports or decks
• Data extractions and analytics workflows
• Scripted operations
• Rapid prototyping when team bandwidth is limited

Solid Choices: Spikes that still ship an artifact (notes/PoC/table).

Avoid For: One-off Q&A, fuzzy ideation without criteria, or work blocked by missing permissions.

Operationalize wins: When a task works, templatize it as a playbook.

Real‑world analytics workflows

The analytics loop is inherently iterative: form a hypothesis, run a query, refine, visualize, and share. Heavy captures this as a durable run with artifacts you can verify and edit. Below are common patterns we see again and again.

Level Up: Advanced Analytics

• Index repos with DeepWiki-class docs first: Ask 'why is column X computed this way?' with a link back to code lines. Navigate without reading every file.
• Map Warehouses: Catalog activity sources and joins; flag reliable tables with data lineage.
• Evolve Schemas: Suggest or add columns (e.g., ARR forecasts) with safe migrations.
• Spot Gaps Early: Surface un-migrated data or missing events before they escalate.
• Segment Deeply: Build conversion or retention views by industry, scale, and region—with transparent filters.
• Track Adoption: Benchmark pre/post-launch metrics (e.g., MCP usage).
• Project Ahead: Layer forecasts with explicit assumptions and confidence bands.

Pro Tip: Always document “Why this column?” inside artifacts. Lineage details dodge pitfalls stand-alone SQL copilots often miss.

Effective Instructions: Clear, Focused Briefs

Precise, well-structured instructions improve agent reliability. Use this proven template for consistent results:

**Goal:**
Your one-line desired outcome.

**Context:**
Key links, status quo, and what is *not* in scope.

**Inputs/Resources:**
URLs, files, APIs (scoped creds), prior artifacts.

**Deliverables:**
Formats (e.g., PR, MD, CSV, Deck) + drop locations.

**Acceptance Criteria:**
Pass/fail checks (schema match, citations required, etc.).

**Constraints:**
Time/budget limits, approved tools, and style rules.

**Milestones/Checkpoints:**
Review points (plan, draft) before the final push.

**Edge Cases/Fallbacks:**
Known tricky spots plus recovery plans.

**Review:**
Approval flow + key proofs (diffs, logs).

VC Brief Templates: Tight, Evidence-Based

Validated against top VC playbooks (4Degrees, Affinity, DealRoom). Enforce narrow scopes and cross-verified sources.

1. Due Diligence Snapshot (Series A/B)

**Goal:** 1-page DD snapshot for <Company> at <Round>.

**Inputs:** Pitch deck, data room, public intel (site, filings, news, pricing), analyst notes.

**Deliverable:** docs/dd/<company>-<round>-snapshot.md — sections: Company, Market/TAM-SAM-SOM, Product, Traction, Team, Risks, Questions.

**Acceptance:** ≥6 cited sources (URLs); competitor matrix [Company | Positioning | Stage | Rev Est. | Customers]; 3 key risks; 5 diligence asks.

**Constraints:** 60 min cap; public data only; confidence per section.

**Milestones:** Outline → Sources → Draft → Polish.

2. Market Sizing + Competitive Scan

**Goal:** Validate market size and map top 10 competitors for <Category> in <Region>.

**Inputs:** Market reports, vendor sites, pricing, funding news, analyst coverage.

**Deliverable:** docs/research/<category>-market-2025.md — TAM/SAM/SOM (method + math), two growth scenarios, competitor matrix (features/pricing/ICP), investment implications.

**Acceptance:** Show top-down and bottom-up math; ≥8 sources; no single-source claims; call out confidence and data gaps.

**Constraints:** 45 min; prioritize primary/recency.

**Milestones:** Method & assumptions → Data pull → Matrix → Write-up.

3. Portfolio KPI Monitor (Pilot)

**Goal:** Stand up a CSV snapshot of monthly KPIs for 3 portfolio cos.

**Inputs:** Public/portfolio updates, newsletters, hiring pages, release notes.

**Deliverable:** data/portfolio-kpis.csv [Company, Month, ARR cue, Growth cue, Hiring cue, Churn cue, Notable events, SourceURL].

**Acceptance:** ≥3 months history each; ≥2 sources per row; README.md explaining heuristics; flag assumptions.

**Constraints:** 30 min; public signals only.

**Milestones:** Schema → 3-row sample → Full file.

Evidence‑first: require URLs and note confidence; prefer triangulated public data over vendor marketing claims.

Prerequisites: Ready to Roll?

• Heavy account + workspace access
• Tailored integrations (data, repos, tools)
• Orchestration and workspace layers managed automatically (fast snapshots keep work reproducible between runs)
• API key configuration for integrations

Integrations: Power Your Agents

Wire MCP connectors with scoped keys and budgets; monitor in one place. For heavy lifts, preload workspace adapters (browser, code, file ops) so every action stays reproducible.

Foundation Pillars

• Secure Onboarding: Least-privilege keys in vaults with hard budgets.
• Explore Schemas: Expose tables and lineage for low-risk querying.
• Execute Robustly: Run SQL/APIs with retries and idempotency.
• Process Outputs: Generate polished visuals, tables, and artifacts.
• Share Seamlessly: Publish linked results with full audit diffs.

Connectors Overview

• Warehouse: Read-only SQL with auto-retries.
• Docs: Cited grounding snippets.
• Repos & Code Indexing: Sandboxed clones, PRs, and sophisticated semantic search tools—enable Q&A on any repository, documentation discovery, dependency mapping, and architecture analysis.
• MCP Marketplace: Datadog (monitoring), Sentry (error tracking), Figma (design context), Airtable (structured data), GitHub/GitLab APIs (automated PR reviews, CI/CD workflows).
• Browser/API: Throttled fetches with safeguards.
• Sheets: Budgeted read/write lanes.
• Dashboards: Embeddable charts for quick review.

Memory & Knowledge: Smart Context Management

Heavy uses four operations to manage context intelligently: Write, Select, Compress, Isolate. Instead of overwhelming agents with information, Heavy strategically controls what they see and when.

• Write Context: Save important information strategically—session state, successful patterns, and proven approaches.
• Select Context: Load only what's relevant for the current task, not everything available.
• Compress Context: Summarize automatically when space gets tight, keeping essential details clear.
• Isolate Context: Keep separate tasks independent, preventing confusion and cross-contamination.

Why This Matters: Poor context management causes agents to fail. Heavy's intelligent approach prevents these failures through strategic information control.

Builders: Design Once, Run Continuously

Transform repetitive work into automated workflows. Heavy's builder interface lets you design agents that run on demand or trigger automatically—responding to code changes, data updates, scheduled times, or business events.

Agent Builder: Your AI Workforce

Create specialized agents for specific tasks—each with its own tools, policies, and validation rules. Think of agents as team members who handle focused responsibilities: one for data analysis, another for code reviews, a third for customer research.

• Interactive Planning: Preview the plan (files, findings) before autonomous run. This front-loads context understanding and reduces mid-execution surprises.
• Natural Language Setup: Describe what you want your agent to do; the builder generates the configuration.
• Manual Mode: For precise control, configure tools, policies, and validation gates directly.
• Tool Assignment: Give each agent only the tools it needs—analytics, code analysis, web search, or database access.
• Policy Integration: Embed guardrails and constraints directly into agent behavior.

Workflow Builder: Orchestrate Complex Tasks

String multiple agents together into workflows that handle multi-step processes. Each workflow follows clear stages—Plan → Research → Act → Verify → Deliver—with checkpoints and human review gates where needed.

• Typed Steps: Each stage knows what it receives and what it must produce.
• Validation Gates: Automatic checks ensure quality before moving forward.
• Artifact Outputs: Every workflow produces reviewable results—diffs, reports, datasets, or recommendations.
• Progress Tracking: Visual timelines show exactly where work stands.

Triggers: Work While You Sleep

Set up agents to respond to real-world signals without manual starts. Start with three high-ROI triggers: PR-opened, build-failed, dashboard-updated. Heavy supports multiple trigger types:

• Schedule Triggers: Daily market summaries, weekly performance reports, monthly audits. Use for model retraining, periodic codebase indexing, or recurring evaluation tasks.
• Event Triggers: PR opened/merged (automated code reviews), build failures (root cause analysis), metric thresholds crossed, customer tickets escalated. Connect GitHub/GitLab APIs, CI/CD webhooks, monitoring systems.
• Data Change Triggers: Updated dashboard, new database records, changed configurations. Trigger data validation, anomaly detection, or report generation.
• Calendar Integration: Pre-meeting briefs, post-meeting summaries, deadline reminders.
• Webhook Triggers: External system events, API callbacks, third-party notifications. Wire Slack messages, Jira ticket updates, or custom application events.

Real Examples

Scheduled Runs: Always Current

Automate freshness—daily briefs or weekly fixes—via isolated, budgeted triggers with approvals. Outputs land as auditable artifacts, routed to PRs or emails for team visibility.

Supports cron/intervals, webhooks, and guardrails to block mishaps before promotion.

Your First Run: Step-by-Step Guide

Follow these steps to launch your first successful agent workflow.

1. Set Goals + Criteria

Craft a tight paragraph with deliverables and metrics. Focus on one artifact—diff, report, deck, or dataset.

2. Compose the Workflow

Lay out Plan → Tool Use → Verify → Learn. Attach the right tools and policies; keep every step small and verifiable.

3. Add Gates & Guardrails

Slot schema checks, policy gates, and merge thresholds. Prefer dry-run lanes until confidence climbs.

4. Run & Review

Execute once, then audit the trace. Use Computer Views for diffs, logs, visuals, and previews.

5. Iterate & Promote

Log misses as updated criteria, adjust prompts or policies, and rerun through a canary gate before promotion.

Evolve Policies: Observe → Reflect → Mutate → Select

Evolve prompts like code: mine traces for rules, tweak surgically, and A/B test via GEPA-style reflective loops for structured feedback.

Breakdown:

• Reflect: Distill fixes for format issues, evidence gaps, or tool misuse.
• Mutate: Apply targeted edits—spec tweaks, domain constants, or search-before-solve rules.
• Select: Prune, then A/B inside the workflows teams already touch.

Observe (Traces) ─→ Reflect (Rules) ─→ Mutate (Edits) ─→ Select (A/B) ─┐ │              │ └──────────────┘

In Practice: Test small, log misses as criteria, and ship updates through canary gates.

Operate Durably: Verification Loops That Compound

The Generation ↔ Verification Cycle

Production agents need tight feedback loops: generate → verify → iterate. Heavy accelerates this cycle through parallel verification, self-testing, and artifact-based evidence. Rule: If tests/linters fail, Regenerate Plan and minimize diff on retry.

• Self-Testing at Each Step: Agents write validation scripts as they work—catching errors before they compound into context poisoning.
• Parallel Validation: Run tests, linters, and checks concurrently; gather evidence without blocking progress.
• Batch Edits + Multi-Action Speed: Batch edits and multi-action speed up refactors; keep guards on.
• Artifact-Based Evidence: Every change produces diffs, logs, screenshots—linked proof for human review.
• Eval-Driven Improvement: Held-out test sets measure real performance; agent-generated feedback identifies tool improvements.

Context-Aware Orchestration

Like Sonnet 4.5's “context anxiety,” Heavy agents monitor their own token budgets—but with guardrails to prevent premature wrap-up:

• Proactive Summarization: At 80% capacity, compress tool outputs; at 90%, snapshot critical state to scratchpad.
• Parallel vs Sequential: Early in context: maximize parallelism for speed. Late in context: focus on finishing critical path.
• Token Budget Visibility: Expose accurate remaining capacity to prevent “running out sooner than expected” behaviors.

Production KPIs

Measure what matters for agents that finish work:

• Completion Rate: % of tasks finished without manual intervention
• Context Efficiency: Tokens per task milestone; tool calls per success
• Verification Pass Rate: % of artifacts passing automated checks first try
• Plan Re-approval Rate: % of runs where editing the plan avoided downstream failures
• Confidence Match Rate: Correlation between agent confidence scores and actual success. Track across runs—high match rates indicate reliable self-assessment, enabling safer automation. Low match rates signal need for additional context, verification gates, or human-in-loop decisions.
• Error Recovery Time: Turns from hallucination to correction
• Hallucination Caps: Hard limits + steering to prevent context poisoning

Views: Inspect & Ship Confidently

Capture artifacts with premium previews—diffs, logs, tables, images, decks—so every edit maps to evidence and reviews fly by.