# From Vision to Version: My Doc-Driven, AI-Assisted Product Workflow [Canonical article](https://www.ashryan.io/writing/my-doc-driven-ai-assisted-product-workflow/) Published: 2025-08-04 How I use a simple wiki structure in my monorepo to manage product alongside AI agents in my IDE. ![](https://images.unsplash.com/photo-1598292977405-b31b7062aeee?auto=format\&fit=crop\&w=2000\&q=80) Photo by [Fred Moon](https://unsplash.com/@fwed?utm_source=ghost\&utm_medium=referral\&utm_campaign=api-credit) / [Unsplash](https://unsplash.com/?utm_source=ghost\&utm_medium=referral\&utm_campaign=api-credit) As a solo founder, I wear every hat: strategy, UX, data, code, infra, support, and more. To stay fast and coherent, I keep a lightweight product system **inside my monorepo** and pair it with a role-specific AI assistants that let me “switch hats” on demand. **TL;DR setup:** - Four core docs live in `wiki/product/` and connect strategy to features. - Features flow from `proposals/` → `epics/` (with milestones) → shipped PRs. - I use Roo modes **(Ask**, \*\*Product Strategist, UX/UI, PM, DB Architect, Code)\*\*at each step to reduce context switching and keep focus and momentum. ## Foundation in the Repo These files let me (and the AI) zoom out. Without them, there’s no shared direction. ### Vision, Mission, and Strategy > `wiki/product/1-vision-mission-strategy.md` The north star. Concise statements that guide trade-offs. This doc answers three questions: - **Vision:** Where are we going? - **Mission:** What do we do to get there? - **Strategy:** How will we do it? **Collxn (short version):** - **Vision:** Be the definitive digital platform for analog music collectors. - **Mission:** Fuel passion and connection for collectors online. - **Strategy pillars:** Dream Interface, Physical↔Digital Bridge, Authentic Community, Cultural Integrity. It’s a living doc, but I try not to change it frequently. ### Process > `wiki/product/2-process.md` *How* I work, in one page: **Roadmap → Theme → Epic → Milestone → Task**. Clear definitions keep scope sane. Without this, an AI companion can flail into inconsistent stabs in the dark. I can point the AI back to this document to make sure it understands how to prepare for coding. ### Roadmap > `wiki/product/3-roadmap.md` A rolling, time-boxed view of **what’s next**, grouped by **Themes**. It’s deliberately short so it actually gets updated. *** These three files—Vision/Mission/Strategy, Process, and Roadmap—ensure every commit traces back to strategy. ## From Idea to Build > `wiki/product/proposals/` → `wiki/product/epics/` A two-step flow that avoids jumping straight from “shower thought” to code while still moving quickly. ### Proposals > `wiki/product/proposals/` This is a scratchpad for the *why* and *what*. I’ll draft the problem, goals, options, and exit criteria (and/or ask Roo to take a pass) then iterate until it reads cleanly end-to-end. Because `/proposals/` is a scratchpad, I tell Roo to **ignore** the directory by default to avoid polluting its context. If the idea holds up (clear, researched, communicable), it **graduates** and I process it into an **Epic**. ### Epics > `wiki/product/epics/` The build blueprint. One markdown file per epic with: **problem, scope, non-goals, risks, milestones, acceptance criteria**. **Sanity check:** Ask your AI agent *“Is this epic a bag of doorknobs?”*. It’s easy for humans and AI agents alike to create a grab-bag of loosely related tasks. Keep epics as small and focused as practical. You’ll get better results from the AI agent and avoid side-effects from wide-spanning changes. I expect to have high confidence that I can hand this Epic document to the coding agent and expect it to stay on track. In turn, the coding agent updates the epic as it works through the constituent milestones. ## My AI Co-Pilot: Roo’s Specialized Modes Roo modes give me focused help where I need it. Without modes, I’d constantly be dragged back into “just code it.” - **💬 Ask Mode** Quick clarifications, references, and “show me three alternatives” prompts without committing changes. I find that this mode is a really nice starting point as it seems to find a good balance between “too much info” (hi, Architect mode) and “too code-thirsty”. - **🧠 Product Strategist Mode** For `1-vision-mission-strategy.md` and early `proposals/`. Pressure-tests the *why*, user value, and alignment with the pillars. - **📈 Product Manager Mode** Turning a validated proposal into an epic in `epics/`: user stories, acceptance criteria, and a milestone/task breakdown that fits `3-roadmap.md` without drift. - **🧮 Database Architect Mode** When an epic touches data: draft/refine `prisma/schema.prisma`, check relationships, constraints, and migration impact. - **🎨 UX/UI Designer Mode** Translating a proposal (e.g., `proposals/nav-bar-strategy.md`) into flows and interaction patterns. Think happy paths, edge cases, and affordances before pixels. (I also keep a `wiki/brand/` directory to keep Designer and Code modes on-brand.) - **💻 Code Mode Last on purpose.** Pair-programming for the full stack. I prefer to have it work against the granular milestones in the epic so I can check progress and challenge decisions as the agent and I go. **Net effect:** faster decisions, fewer rewrites, tighter handoffs. ## Wrapping Up Effective collaboration with AI agents starts with a **shared, durable memory**. The product docs create that memory, capturing **history** (why decisions were made), **state** (what’s planned and in progress), and **process** (how ideas become code). When agents read and write against these files, they align to the same ground truth, reduce drift, and make decisions that stay consistent over time. A simple pattern works well: - **Vision/Process/Roadmap** anchor strategy and current priorities. - **Proposals → Epics** create a clean handoff from exploration to execution. - **Role-specific modes** (Ask, Strategist, Designer, PM, DB, UX/UI, Code) scope an agent’s behavior to the job at hand. If you want the skeleton to copy, here’s the starter tree I’m currently using: ```plaintext wiki ├── brand │ └── ... ├── development │ └── ... ├── product │ ├── 0-README.md │ ├── 1-vision-mission-strategy.md │ ├── 2-process.md │ ├── 3-roadmap.md │ ├── 4-inbox.md │ ├── epics │ │ ├── _TEMPLATE.md │ │ ├── epic-1-auth-foundations.md │ │ ├── epic-2-auth-frontend.md │ │ ├── epic-3-discogs-import.md │ │ ├── epic-4-daily-drops.md │ │ ├── epic-5-user-settings.md │ │ ├── epic-6-nav-bar-mvp.md │ │ ├── epic-7-public-site-mvp.md │ │ └── ... │ └── proposals │ ├── blog.md │ ├── nav-bar-strategy.md │ ├── public-site-copy.md │ ├── unified-footer.md │ └── ... └── README.md ``` (The only file there I didn’t cover is `4-inbox.md`. This is simply a place to stash thoughts as I work for future processing.) To try this: 1. Copy the `wiki/product/` skeleton 2. Keep each doc short 3. Require agents to reference them before acting 4. Require agents to reference them **after** acting **This is definitely going to feel slow at first** if you’re used to standard vibe coding. But if you’re trying to build a product and ship it, you’ll get a lot more mileage out of setting the context, prescribing the process, and building your AI team first.