vision

name

vision

description

Generate or update the project vision document (vision.md) for the team's Flutter personal finance app. Use this skill whenever the user asks to create a vision doc, write up the project vision, capture "what we're building", document guiding principles, or record the team's goals and architectural rationale. Triggers on phrases like "create a vision", "write our vision", "document the vision", "vision.md", "what are we building", "capture our goals", even if they don't use the exact word "vision".

Synthesize the team's context into a concise, opinionated vision.md that helps the team make decisions faster.

Step 1 — Gather context

The CLAUDE.md files for this project are already in your context. Extract:

• Domain: what the app covers (income, budgeting, savings, investments)
• Tech stack: Flutter, why it was chosen, what it enables
• Architecture: event sourcing — what that means for this app
• Quality bar: correct calculations (primary), web-first (primary form factor)
• Workshop intent: vibe coding, exploring how to work with AI agents

If any of these feel thin — especially domain depth or architectural implications — use the /research skill with a focused question before writing. One research call at most; don't expand scope.

Step 2 — Write vision.md

Save to teams/boris-and-martin/exercise_one/vision.md. Create exercise_one/ if it doesn't exist yet.

Use exactly this structure:

# Vision — [App Name or working title]

> [One sentence: what it is, who it's for]

## What We're Building

[2–3 sentences. Concrete product description — what does a user actually do with this? What does it feel like?]

## Why

[2–3 sentences. Why this domain for the workshop? What's the real goal — learning to work with AI agents, not shipping a product. What would make this exercise a success?]

## Architecture

Bullet list — each decision gets one line of rationale:

- **Flutter (web-first)**: [why — single codebase, web as primary form factor, what this means for trade-offs]
- **Event sourcing**: [why — append-only log, state derived from replay, what this means for how we model features]
- **[Any other decisions that emerge from context]**

## Quality Bar

[What "done well" means for this project. Be concrete. The CLAUDE.md is explicit: calculations must be correct above all else, and the web build is the primary form factor.]

## Guiding Principles

3–5 short principles — actionable rules the team can actually apply when trade-offs come up. Each one should help someone decide what to do in an ambiguous situation. Bad: "Write clean code." Good: "Model new features as events first, projections second — if you're reaching for mutable state, stop and rethink."

Tone and intent

Write in first-person plural ("we"). Be specific and opinionated — a vision doc that tries not to offend anyone is useless. Every sentence should help someone make a faster decision.

Don't just paraphrase the CLAUDE.md. Synthesize: pull out the implications of the decisions, not just the decisions themselves. The guiding principles especially should feel earned, not obvious.

Step 3 — After writing

Tell the user where the file lives and ask if they'd like to tweak anything. Offer to commit with /commit once they're happy.