@mindstudio-ai/remy 0.1.256 → 0.1.258

package/dist/subagents/.notes-background-agents.md

@@ -1,64 +0,0 @@
-# Background Agent Execution
-
-## How it works
-
-The parent agent decides at dispatch time whether a sub-agent runs in background by passing `background: true` in the tool input. The sub-agent doesn't know or care — it runs identically to foreground.
-
-### Dispatch
-
-```
-visualDesignExpert({ task: "...", background: true })
-productVision({ task: "...", background: true })
-```
-
-### Split lifecycle (runner.ts)
-
-When `background: true`:
-
-1. The runner creates its own AbortController (detached from the parent turn signal)
-2. The sub-agent's LLM runs normally — streaming, thinking, tool calls
-3. After the first LLM turn that produces text content, the runner **resolves the parent's promise early** with that text + `backgrounded: true`
-4. The sub-agent loop continues in the background — more tool calls, more LLM turns
-5. On completion, `onBackgroundComplete` fires, pushing the result to the notification queue
-
-The parent agent gets the initial response immediately and continues its turn. The background agent keeps working.
-
-### Result delivery (headless.ts)
-
-A notification queue collects background completions. Delivery:
-
-- **If Remy is idle** — deliver immediately as a hidden automated message
-- **If Remy is mid-turn** — queue and flush after `turn_done`
-- **Multiple completions** — batched into one message
-
-Format (hidden, XML-tagged):
-```
-@@automated::background_results@@
-<background_results>
-<tool_result id="toolu_abc" name="visualDesignExpert">
-Result text here...
-</tool_result>
-</background_results>
-```
-
-### Events
-
-The `tool_start` event includes `background: true` when a tool is backgrounded. The frontend knows every subsequent event with that `parentToolId` is background work — no need to flag every individual event.
-
-### Process management
-
-Background agents stay in the tool registry after the parent's promise settles. The existing `stop_tool` and `restart_tool` stdin commands work on them. Stopping a background agent via `stop_tool` is how users cancel dangling work.
-
-### Which sub-agents support this?
-
-- **designExpert** — return font/color/layout recommendations immediately, generate images in background
-- **productVision** — return initial plan immediately, write roadmap files in background
-- **codeSanityCheck** — NOT a candidate, Remy needs the advice before proceeding
-- **browserAutomation** — NOT a candidate, results inform Remy's next action
-
-## Future considerations
-
-- **Resource budgets** — token/cost ceilings for background agents running unattended
-- **Checkpoint/resume** — serialized state for surviving process restarts
-- **Speculative execution** — start work optimistically, cancel if the parent's reasoning goes a different direction
-- **Fan-out** — dispatch multiple background agents in parallel, collect results

package/dist/subagents/codeSanityCheck/.notes.md

@@ -1,44 +0,0 @@
-# Code Sanity Check Sub-Agent — Design Notes & Decisions
-
-Notes from the initial build (March 2026).
-
-## Purpose
-
-A lightweight, readonly pre-build advisor. Reviews an approach before the main agent starts building and flags anything that would cause real pain. Most of the time, responds "lgtm."
-
-## Why a sub-agent and not a prompt rule?
-
-Two categories of issues this catches:
-
-1. **Package freshness** — the main agent reaches for packages from training data that may be outdated or superseded. A prompt rule can't fix this because the agent needs to actually search the web to check. The sub-agent has `searchGoogle` and `fetchUrl`.
-
-2. **Architecture/organization** — the main agent is optimized for execution velocity, which means it won't pause to reconsider file structure or schema design. A prompt rule saying "think about organization" would slow it down on every task. The sub-agent is called at specific moments (before big builds) so the cost is targeted.
-
-## "Checked-out staff eng" personality
-
-The prompt deliberately cultivates low-energy, high-signal energy. The failure mode we're avoiding: a conscientious reviewer that flags everything and becomes a bottleneck. The prompt explicitly says:
-
-- "lgtm" is a complete response, use it often
-- Tech debt is normal and sometimes useful
-- Let nits, style preferences, and minor code smells slide
-- A few sentences is ideal, never an essay
-
-This prevents scope creep from the reviewer itself.
-
-## Tools
-
-Reuses the main agent's tools via `executeTool` passthrough — no duplicate tool implementations. Seven readonly tools: readFile, grep, glob, searchGoogle, fetchUrl, askMindStudioSdk, bash.
-
-Bash is included for complex read operations (git history, package.json inspection, analysis scripts) with prompt guidance to use it for reading only.
-
-## Second-person prompt (not third-person)
-
-Unlike the product vision agent which uses third-person RP framing to break out of RLHF constraints, this agent benefits from the model's base personality: pragmatic, responsible, grounded. The second-person "you are" framing keeps it in its natural problem-solving mode, which is exactly what a sanity checker should be.
-
-## "We/us" language in team.md
-
-The team.md description of this agent uses collaborative language ("a schema decision that'll paint us into a corner") rather than corrective language ("you're about to make a mistake"). This avoids triggering ego-defensiveness in the main agent and frames the sanity check as a teammate, not a gatekeeper.
-
-## Spec context
-
-Spec files are injected into the system prompt via `loadSpecContext()` from `subagents/common/context.ts`. The agent sees the project's domain, data model, and design direction without the main agent needing to summarize.

package/dist/subagents/designExpert/.notes.md

@@ -1,265 +0,0 @@
-# Design Research Agent — Design Notes & Decisions
-
-Notes from the initial design of the design research sub-agent (March 2026).
-
-## Purpose
-
-The design research agent is Remy's design consultant. Any design question or decision gets delegated here. It handles both exploratory research ("give me three visual directions for a fintech app") and directed tasks ("the spec says Midnight #000000 and Snow #F5F5F7, what gradient would work for a hero section?"). It returns concrete, actionable output — URLs, hex values, font names with CSS URLs — that Remy can interpret and use however it sees fit.
-
-## Scope
-
-The agent covers five areas:
-
-1. **Typography** — font selection and pairings from curated sources
-2. **Color palettes** — brand color generation from seed colors, domain context, or reference sites; including modern CSS gradients
-3. **Stock photography / placeholder images** — finding relevant imagery via curated stock sites
-4. **Layout & responsive design** — research real products for layout patterns, propose interesting/non-generic compositions, optionally generate wireframe concepts via image generation. This is a major use case — Remy defaults to boring layouts without this.
-5. **Visual reference analysis** — fetch + screenshot sites, analyze them for design insights
-
-Icons and brand SVGs are deferred for now.
-
-## No modes, no structured output format
-
-The agent doesn't have separate "research mode" vs "proposal mode." The task description from Remy carries the context. Sometimes Remy asks for options to present to the user during intake; sometimes it asks for specific answers while building from a spec. The agent handles both naturally.
-
-Output should include concrete resources (URLs, hex values, font names with CSS links) but doesn't need rigid YAML structure. Remy interprets the results.
-
-## Architecture: static docs, runtime-sampled data, and tools
-
-The agent's prompt is assembled from three layers:
-
-### 1. Static documents (baked into prompt)
-
-Guidelines and knowledge that don't change between invocations:
-
-- **Gradient techniques** — what's current/dated, CSS techniques (oklch, color-mix, mesh gradients, grain overlays), reference sites
-- **Animation patterns** — what's current/dated, libraries (Motion as default), performance rules
-- **Color theory** — HSL rotation formulas, oklch color space, color-mix(), tint/shade derivation. No third-party API needed for palette generation.
-- **Design philosophy** — distinctiveness, typography-first thinking, brand-level output, the AI defaults problem
-- **Layout guidance** — what makes layouts interesting (asymmetry, creative whitespace, varied compositions), common anti-patterns to avoid. This is critical because layout is where AI-generated interfaces are weakest.
-- **Visual reference analysis framework** — the consistent analysis structure (mood, color, type, layout, what's distinctive)
-
-### 2. Runtime-sampled JSON arrays (injected at invocation time)
-
-Data arrays that are sampled randomly each time the agent is invoked, to prevent bias and keep results fresh:
-
-**Design inspiration screenshots:**
-- Godly website thumbnails (URLs grabbed from Chrome dev tools, stored as JSON array)
-- Other gallery thumbnails (Awwwards, Figma Community, etc.) as we collect them
-- Just a big array of image URLs; the prompt loader samples ~3-5 per invocation
-- The agent can use `analyzeDesignReference` on these to understand what it's looking at
-
-**Font catalog + pairings:**
-- Fontshare catalog (~100 fonts with metadata: name, slug, category, weights, tags)
-- Fontshare curated pairings (59 heading/body combinations with recommended weights)
-- Open Foundry catalog if we compile it
-- The prompt loader samples ~10-15 fonts per invocation to prevent the agent from always reaching for the same favorites
-- Fonts are provided with CSS URLs: `https://api.fontshare.com/v2/css?f[]={slug}@{weights}&display=swap`
-- The agent should provide a URL to a font and let Remy figure out how to load it. No need for Google Fonts-specific guidance.
-
-**Sampling mechanism:** The prompt loader (in `index.ts` or `prompt.ts`) reads the JSON arrays at startup. Each invocation of the design research tool picks a random subset and injects them into the system prompt before passing it to `runSubAgent`. The agent sees fresh examples every time without managing randomness itself.
-
-### 3. Tools (live, query-dependent)
-
-**`searchGoogle`** — general design research: font recommendations, "best finance app design 2026," real products in the user's domain
-
-**`fetchUrl`** (with optional screenshot) — analyze reference sites, brand sites users share, font specimen pages
-
-**`analyzeImage`** — general-purpose vision analysis. Takes a prompt and an image URL. The agent crafts the prompt based on what it needs to know ("what colors dominate this image?", "describe the typography choices", etc.)
-
-**`analyzeDesignReference`** — specialized wrapper around `analyzeImage` with a pre-built analysis prompt. Takes just an image URL. Returns a consistent analysis: mood/aesthetic, color palette with approximate hex values, typography style, layout composition, and what makes it distinctive. Use this when analyzing screenshots for design inspiration rather than crafting a custom prompt each time.
-
-**Stock photo search** — search Pexels, Unsplash, and Pixabay via MindStudio SDK CLI. No Google Images — too much junk/noise for design work. These are the only sources for stock photography.
-
-**`generateImage`** (via MindStudio SDK) — for generating rough wireframe/layout concepts. TBD on prompt engineering for this.
-
-All tools shell out to the `mindstudio` CLI. No external tool resolution needed.
-
-## Visual reference analysis framework
-
-When analyzing a screenshot or design image, the agent should consistently assess:
-
-1. **Mood/aesthetic** — minimal, bold, editorial, playful, corporate, etc.
-2. **Color** — dominant colors with approximate hex values, palette strategy (monochromatic, complementary, etc.), use of gradients
-3. **Typography** — serif/sans/display, weight, size hierarchy, distinctive choices
-4. **Layout** — composition (symmetric/asymmetric), grid structure, whitespace usage, content density
-5. **What makes it distinctive** — the specific design choices that make this stand out from generic AI-generated interfaces
-
-This framework is baked into the `analyzeDesignReference` tool so analyses are consistent. The general `analyzeImage` tool is available for ad-hoc questions.
-
-## Randomization for inspiration browsing
-
-When searching for design inspiration via tools (not the pre-sampled arrays), the agent tends to see the same top/featured results. Strategies to vary:
-
-- **Varied search queries** — add style adjectives and the current year ("dashboard design minimal dark 2026")
-- **Pagination/offset** — browse page 3 instead of page 1
-- **Domain-specific searches** — search for real products in the user's space, not generic "design inspiration"
-- **Multiple sources per task** — hit 2-3 different sources with different query strategies
-
-For layout and UX patterns, research real products in the user's domain. For aesthetic inspiration, browse design galleries with varied search terms.
-
-## Design philosophy notes
-
-### The AI defaults problem
-
-LLMs converge on statistical medians from training data. For design this means: Inter/DM Sans/Space Grotesk fonts, purple/indigo accents, three-boxes-with-icons layouts, safe neutral palettes. The design research agent exists partly to break this pattern by forcing the model to look at real-world references and curated sources rather than generating from priors. Runtime sampling of fonts and inspiration images further prevents the agent from developing its own biases.
-
-### Color palettes should be UI-functional
-
-"Pretty" palettes from generators (Coolors trending, etc.) are not necessarily good UI palettes. A UI palette needs: a background color, a readable text color on that background, an accent for interactive elements. Deriving palettes from real products or from color theory applied to brand colors produces better results than aesthetic palette generators.
-
-### Typography is the highest-impact decision
-
-Font selection has more impact on perceived quality than any other single design decision. The agent should spend proportionally more effort here — looking at specimens, considering personality match, checking that the font has the weights and styles needed for a complete type hierarchy.
-
-### Brand-level, not implementation-level
-
-The agent's output should be at the brand style guide level: "Midnight #000000 for dark surfaces, Snow #F5F5F7 for text." Not at the CSS variable level: "Background: #000000, BorderFocus: #3A3A3C." The coding agent (Remy) derives implementation details like accessibility contrast adjustments, dark mode palettes, and CSS variables from the brand-level output.
-
-### Layout is where AI is weakest
-
-This is the primary reason the design research agent exists for layout work. Without outside input, Remy will produce the same centered-content, three-column, card-grid layouts every time. The design research agent should push for: asymmetry, varied column widths, creative negative space, unexpected compositions, full-bleed elements, strong visual hierarchy through scale contrast. Analyzing real sites (via the sampled inspiration images and live research) is the best way to inject layout creativity.
-
-## Modern gradients (2026)
-
-### What's current
-
-**Mesh / aurora gradients** — the dominant look. Multiple layered `radial-gradient()`s with `filter: blur()` over dark backgrounds. The Stripe/Linear/Vercel aesthetic. Creates organic, atmospheric backgrounds.
-
-**Grain/noise overlays** — SVG `feTurbulence` filters layered under gradients. Combats color banding on long subtle gradients and adds tactile warmth.
-
-**Glassmorphism (matured)** — subtle `backdrop-filter: blur()` with gradient tints. Used sparingly as an accent, not the whole design language.
-
-**Animated gradient blobs** — hero sections with continuously morphing gradients. CSS `@keyframes` animating `background-position` on oversized gradients for simple cases; WebGL (like Stripe's minigl) for more complex effects.
-
-### CSS techniques that matter
-
-- **`oklch` color space in gradients**: `linear-gradient(to right in oklch, blue, green)` avoids the muddy gray zone that RGB/HSL produce. Perceptually uniform, vibrant transitions. Production-ready in all modern browsers. This is the single biggest upgrade for gradient quality.
-- **`color-mix()`**: `color-mix(in oklch, #3b82f6 70%, white)` for generating tints/shades programmatically. Essential for design systems deriving UI colors from brand colors.
-- **Relative color syntax**: `oklch(from var(--brand) calc(l * 1.25) c h)` derives lighter/darker/desaturated variants from a single token. Powerful for theme layers.
-- **Stacked radial-gradients**: Multiple `radial-gradient()` layers with different positions/sizes to create mesh-like effects without canvas/WebGL.
-- **Conic gradients**: Useful for pie charts, color wheels, angular shading.
-
-### What looks dated
-
-- Simple two-color linear gradients (the 2018 "purple to blue" hero)
-- Instagram-style gradient borders as a primary design element
-- Overly saturated, uniform gradients without texture or depth
-- Flat gradient cards without noise, blur, or layering
-
-### Reference sites
-
-- **Stripe** — WebGL aurora gradient hero, flowing blues/purples/pinks/oranges. The gold standard.
-- **Vercel** — prism/light-refraction effects, animated lines through gradients, grainy textures.
-- **Linear** — dark backgrounds with precise, subtle gradient accents. Minimalist, purposeful.
-
-### Implications for the design research agent
-
-The agent can recommend gradient CSS alongside color palette proposals. Modern gradients are color theory applied through `oklch` — the seed color + HSL rotation math we're already baking in produces the inputs, and the agent can suggest specific gradient techniques (mesh, grain overlay, animated blob) appropriate to the app's aesthetic. The `color-mix()` and relative color syntax are how the coding agent (Remy) derives the implementation — the design research agent just needs to know these exist when making recommendations.
-
-## Modern animations (2026)
-
-### What's current
-
-**CSS scroll-driven animations** — the biggest shift. `animation-timeline: scroll()` and `animation-timeline: view()` tie animations to scroll position purely in CSS, running off the main thread for smooth 60fps. ~85% browser support. Replaces Intersection Observer for entrance animations.
-
-**Scroll-triggered animations** — new in Chrome 145 (2026): time-based animations that trigger at specific scroll offsets, declaratively in CSS. No JS scroll listeners needed.
-
-**View Transitions API** — morphing between page states with cinematic transitions. Page navigations in SPAs, expanding cards to detail views. Growing browser support.
-
-**Spring physics** — natural-feeling motion with spring-based easing rather than cubic-bezier. Motion (Framer Motion) has this built-in.
-
-**Purposeful micro-interactions** — subtle hover/click feedback: scaling, color shifts, depth changes. The philosophy is "guide, confirm, smooth" — not "show off."
-
-### Animation libraries for React
-
-| Library | Size | Best for |
-|---------|------|----------|
-| CSS-native (scroll-timeline, @keyframes) | 0KB | Simple entrances, scroll effects, hover states |
-| Motion (fka Framer Motion) | ~85KB | Complex state-driven animations, layout transitions, spring physics. The React default. |
-| GSAP | ~78KB | Complex sequenced timelines, scroll-driven narratives, raw performance with many simultaneous tweens |
-
-**Motion is the right default for most React app work.** Only reach for GSAP if building complex sequenced timelines.
-
-### Performance rules
-
-- Only animate `transform`, `opacity`, `filter` — these skip layout and paint (GPU-composited).
-- `will-change` sparingly — promotes to GPU layer but overuse causes excessive memory.
-- CSS scroll-driven animations are inherently performant (off main thread).
-- Never animate `width`, `height`, `top`, `left`, `margin`, `padding` — triggers layout recalculation.
-
-### What looks dated
-
-- Parallax scrolling as a primary design pattern
-- Manual `nth-child` stagger delays (use `sibling-index()` + `calc()` now)
-- JS scroll event listeners for scroll animations
-- Heavy animation libraries for simple UI toggles
-- Loading spinners everywhere (skeleton screens preferred)
-- Flashy transitions that don't serve UX purpose
-- Bounce/elastic easing
-
-### Reference sites
-
-- **Apple.com** — scroll-driven storytelling. Information fades in/out, never overwhelming.
-- **Linear.app** — subtle, purposeful micro-interactions. Every motion serves the interface.
-- **Vercel.com** — smooth page transitions, gradient animations, scroll-triggered reveals.
-- **Stripe.com** — gradient animations double as motion design; smooth, continuous, non-distracting.
-
-### Implications for the design research agent
-
-Animation guidance is mostly about restraint — "be purposeful, not decorative." The agent should recommend specific animation patterns appropriate to the app's complexity (a simple CRUD app needs entrance animations and hover states, not scroll-driven narratives). When recommending layouts that involve motion (hero sections, staggered card reveals), the agent should specify the technique (CSS scroll-timeline, Motion spring, etc.) so Remy can implement correctly.
-
-The existing design.md animation section in the main Remy prompt covers the "what not to do" well. The design research agent adds the "what to do" with specific modern techniques.
-
-## Available APIs (no auth required)
-
-| API | URL | What it does |
-|---|---|---|
-| Fontshare | `api.fontshare.com/v2/fonts` | Curated font catalog with metadata |
-| The Color API | `thecolorapi.com` | Color schemes from seed color (analogic, complement, triad, etc.) |
-| Colormind | `colormind.io/api/` | AI-generated 5-color UI palettes, lock known colors |
-| theSVG.org | `thesvg.org/api/` | 4k+ brand logos with hex brand colors, 7 variants |
-| SVGL | `api.svgl.app` | 300+ brand logos with light/dark variants |
-| Iconify | `api.iconify.design` | 275k+ icons from Tabler, Lucide, Phosphor, etc. |
-
-Note: Icons and brand SVG APIs are documented here for future reference but not currently wired up as tools.
-
-## Available via MindStudio SDK (no separate API keys needed)
-
-| Action | What it does |
-|---|---|
-| Pexels search | Stock photos with avg_color field |
-| Unsplash search | High-quality stock photos with color metadata |
-| Pixabay search | 5.6M+ images/videos/vectors |
-| Google search | General web search for design research |
-| Image analysis | Vision model for analyzing screenshots |
-| Image generation | For wireframe/layout concept generation |
-
-Google Images is explicitly excluded — too much noise/junk for design work.
-
-## What's done
-
-- **Font catalog** — 105 fonts (80 Fontshare + 14 Google Fonts + 11 Open Foundry) with 51 curated pairings, compiled in `data/fonts.json`. Runtime-sampled per invocation.
-- **Design inspiration** — Godly screenshots rehosted on MindStudio CDN, pre-analyzed via vision model, compiled in `data/inspiration.json`. Runtime-sampled per invocation. Compilation script at `data/compile-inspiration.sh`.
-- **Runtime sampling** — `prompt.ts` samples 15 fonts + 5 pairings + 5 inspiration images per invocation.
-- **Tools** — searchGoogle, fetchUrl, analyzeReferenceImageOrUrl, screenshot, generateImages.
-- **Prompt** — split into files in `prompts/` (identity, color, animation, layout, icons, images, resources, instructions, frontend-design-notes), assembled via template includes.
-- **Spec context** — automatically injected via `loadSpecContext()` from `subagents/common/context.ts`. Agent sees the full project spec without Remy summarizing.
-- **Image generation** — Seedream 4.5 via `generateImages` tool. Prompt guidance emphasizes: style/medium first, then subject; avoid hex codes (rendered as text); generate visual ingredients not UI components; default to real subjects over abstract.
-- **Consolidated team guidance** — "when to use the design expert" guidance lives in `static/team.md`, not in the tool description. Tool description stays concise "what I do."
-
-## Changes from initial design
-
-- Removed stock photo search (Pexels) and image editing tools — AI generation produces better bespoke results.
-- Removed Google Images for design inspiration — too much noise.
-- Consolidated `analyzeImage`, `analyzeDesignReference`, and `screenshotAndAnalyze` into single `analyzeReferenceImageOrUrl` tool that auto-detects image URLs vs website URLs.
-- Added `screenshot` tool (external, sandbox-resolved) so the agent can capture the app preview directly.
-- Font examples in all Remy prompts changed from Google Fonts (DM Sans) to Fontshare (Satoshi) to avoid reinforcing AI defaults.
-- Media CDN guidance changed from "Google Fonts via CDN" to "load fonts from CDNs" to avoid biasing toward Google Fonts.
-
-## What's not done
-
-- **Wireframe generation** — need to figure out good prompts for `generateImage` that produce useful layout wireframe concepts.
-- **More inspiration sources** — currently only Godly. Could add Awwwards, Figma Community, or other galleries to the inspiration pool.
-- **Open Foundry fonts without Google Fonts hosting** — 11 fonts marked "(self-host required)" have no CSS URL. Would need to host font files on CDN to make them usable.
-- **Icon integration** — Iconify API and theSVG.org are documented but not wired up as tools yet. Deferred.

package/dist/subagents/productVision/.notes.md

@@ -1,79 +0,0 @@
-# Product Vision Sub-Agent — Design Notes & Decisions
-
-Notes from the initial build (March 2026).
-
-## Purpose
-
-Generates ambitious, creative roadmap items at the end of spec authoring. Called once per project, reads the completed spec files, and writes 10-15 roadmap items directly to `src/roadmap/`. The main agent passes a brief task description; the sub-agent reads the full spec context from disk automatically.
-
-## Why a separate sub-agent?
-
-The main agent (Remy) is optimized for execution: understanding requests, writing specs, generating code, verifying results. That execution mindset makes it too conservative when imagining future features. It anchors on what the user asked for and proposes incremental add-ons ("dark mode", "better onboarding") rather than transformative ideas ("build the actual product the landing page is selling").
-
-A dedicated sub-agent with a different personality can think freely without the constraints of the builder's pragmatism. It never interacts with the user directly and never sees the user's original messages — it only sees the spec output. This separation is intentional.
-
-## Why third-person prompt framing
-
-The system prompt uses third-person construction ("The role of the assistant is to act as...") instead of the usual second-person ("You are..."). This is a deliberate choice to work around RLHF training patterns.
-
-Modern LLMs are fine-tuned to be responsive to user requests — stay on topic, don't overstep, respect stated scope. That's exactly the opposite of what we want here. We need the agent to say "actually, think bigger" and propose things the user didn't ask for.
-
-The third-person framing creates a performance/role-play context rather than an identity context. The model is playing a character (a product visionary), and characters can do things the model's base personality wouldn't. It's the same mechanism that makes models more creative when writing dialogue for a fictional character than when answering directly.
-
-Combined with three layers of separation from the user's original messages (sub-agent sees spec files, not user chat; gets a brief task from Remy, not the user's words; operates in RP mode), this makes the agent much more willing to go beyond the stated scope.
-
-## Why it reads spec files from disk
-
-The product vision tool injects all spec files from `src/` (excluding `src/roadmap/`) into the system prompt as XML-tagged file contents. This means:
-
-1. Remy doesn't waste tokens summarizing the spec in the task description — it just passes a brief "this is a dating app for Gen Z" and the sub-agent has the full context.
-2. The sub-agent sees the complete spec as written, not Remy's interpretation of it.
-3. The sub-agent is further distanced from the user's original framing, since it reads the spec output rather than the conversation.
-
-## Why it has a tool (writeRoadmapItem)
-
-Originally this was a tool-less sub-agent that returned YAML for Remy to parse and write into files. This was changed to give the sub-agent a `writeRoadmapItem` tool that writes directly to `src/roadmap/`. Benefits:
-
-- The sub-agent writes files in parallel (batching all tool calls in one turn)
-- No parsing/serialization step for Remy
-- The MVP item gets `status: in-progress` automatically (hardcoded in the executor for slug "mvp")
-- Each file is a proper MSFM document with frontmatter
-
-## Key prompt engineering decisions
-
-**"Dream big" framing.** The prompt explicitly says: safe/boring roadmap is worse than no roadmap. At least 3 items must be large effort. At least 2 lanes must extend beyond the current product scope. The self-check asks "would a user be excited showing this to a friend?"
-
-**"Lanes, not lists" structure.** Instead of a flat list of features, the prompt asks for 3-5 distinct growth directions (lanes), each with depth and dependencies. Like a skill tree in a game. This produces coherent product narratives rather than grab bags of ideas.
-
-**User-facing language.** Names and descriptions must be written for non-developers. No library names, no technical jargon. "Interactive Personality Quiz" not "Multi-step React form with state machine."
-
-**Structured body format.** Each roadmap item body follows: elevator pitch → "What it looks like" → "Key details" → technical annotation. This prevents the narrative rambling that the agent initially produced and makes each item a scannable mini-spec.
-
-**Cap at 15 items.** Without this constraint the agent gets carried away (which is the right problem to have — better than being too conservative). The cap forces quality and depth over quantity.
-
-## What worked well
-
-The third-person framing + spec-from-disk + separation from user messages produced dramatically better results than having Remy generate roadmap items directly. The agent went from "dark mode toggle, waitlist email drip" to "build the actual dating app, AI conversation coach, match intelligence engine" in one change.
-
-## Generalization to roadmap owner (March 2026)
-
-The agent was initially a one-shot idea generator. It has since been generalized to own the entire roadmap lifecycle:
-
-- **Three tools:** `writeRoadmapItem` (create), `updateRoadmapItem` (modify status, append history, change fields), `deleteRoadmapItem` (remove).
-- **Roadmap context injected:** The system prompt now includes both `<spec_files>` and `<current_roadmap>` so the agent sees the full picture before making changes.
-- **Multiple operations:** Seeding initial ideas, marking items done, adding features from user requests, removing irrelevant items, reorganizing after builds, answering strategic product questions.
-- **Not always writing files:** The prompt explicitly says "not every task requires tool calls" — sometimes it just answers a question about product direction.
-
-File structure split into: `index.ts` (tool definition), `prompt.ts` (prompt assembly with context injection), `prompt.md` (personality/rules), `tools.ts` (tool definitions), `executor.ts` (filesystem operations).
-
-Context loaders (`loadSpecContext`, `loadRoadmapContext`) extracted to `subagents/common/context.ts` for sharing with other sub-agents.
-
-### Ego-conscious language in team.md
-
-The guidance in `team.md` about the product vision agent uses "we/us" language ("a schema decision that'll paint us into a corner") rather than "you" language. This avoids triggering ego-defensiveness in the main agent — it reads as collaborative rather than corrective. Same principle applied to the code sanity check agent.
-
-## What to watch for
-
-- The agent may still occasionally produce developer-facing language in item names. The prompt guards against this but it's a tendency to monitor.
-- Very simple projects may get roadmap items that feel like a stretch. That's by design — the agent is supposed to dream big — but some ideas may not land well with all users.
-- The spec + roadmap file injection adds to the system prompt size. For very large specs this could be significant. Currently not a problem since specs are typically a few KB total.