# 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.