vision-builder-en

name	vision-builder-en
description	Skill for defining a clear project vision and generating all core project documentation. MANDATORY TRIGGERS: "build project vision", "define the project", "what are we building", "project scope", "start a project", "plan the project", "create vision", "I want to build X", "structure my idea", "project architecture", "let's define this", "vision document", "where do we start", "project foundation", "before we write code". Use when: user describes an idea and wants to structure it, needs to go from idea → stack → phases, no clear point A or point B defined yet. Do NOT use: if the project is already in progress and vision is locked with no changes needed.
metadata	{"author":"N.V","version":"1.0","lang":"en"}
user-invocable	true

Purpose

Turn a rough idea (or existing context) into a locked project vision and a set of living working documents. The vision is the anchor — all other files derive from it and must stay consistent with it throughout the project lifecycle.

Output Files

File	Role	Stability
VISION.md	What, why, A→B, end result. Read this to understand the project.	Stable after approval
REQUIREMENTS.md	Technical + non-technical requirements	Stable, minor updates OK
PHASES.md	Execution phases + sub-tasks that emerge during work	Living document
WORKFLOW.md	Tools, agents, MCPs, services used in the project	Updated when stack changes

---

Step 1 — Read Context First

Before asking anything, check what already exists:

1. Read VISION.md if it exists in the project root
2. Scan the current conversation for described goals, ideas, or decisions
3. Check REQUIREMENTS.md, PHASES.md, WORKFLOW.md if present

Build an internal picture:

• What does the user want to build?
• What is the current state (point A)?
• What is the desired end state (point B)?
• What is known about the stack?
• What gaps remain?

Only ask about the gaps. Never re-ask what is already clear from context.

---

Step 2 — Clarifying Questions (one at a time)

Ask only what you don't know. One question per message, always.

Core questions to resolve if not already clear:

1. Point A: What exists right now? (existing code, manual process, nothing?)
2. Point B: What does success look like at the end? (specific, observable outcome)
3. Why: What problem does this solve and why does the current situation fail?
4. End result format: What does the user/system receive? (file, API response, service, etc.)
5. Stack: What technologies are preferred or already decided?
6. Constraints: Timeline, team size, technical limits — anything that shapes decisions?

If the user already answered in the conversation, confirm understanding instead:

"I understand the goal as X — is that right?"

---

Step 3 — Stack + Current Versions

Once the stack is defined or decided:

1. Use context7 to pull current stable versions for each major dependency
   • resolve-library-id → query-docs for version and key APIs
   • Only pull versions at this stage, not full documentation
2. Add versions to WORKFLOW.md

Use context7 for its direct purpose: finding current versions and authoritative docs. Keep it simple — just the versions.

---

Step 4 — Generate the Documents

Generate files in order. After each file, wait for user confirmation before proceeding.

VISION.md

# [Project Name] — Vision

## What We're Building
[One paragraph. Clear, no jargon. Someone unfamiliar with the project should understand it.]

## Point A — Current State
[What exists now. What the pain point is. Why this project is needed.]

## Point B — End State
[What exists after the project is done. Specific and observable.]

## Why
[The problem this solves. Why the current situation is not acceptable.]

## End Result
[What the user/system receives. Format, interface, deliverable.]

## MVP
[Smallest version that proves the idea works. Explicit about what is cut.]

## Done When
[A specific, verifiable condition. "I can run X and get Y." Not "it works."]

## Stack
[Technologies + versions. Only what is confirmed.]

This file is an anchor. Once approved, it does not change unless the fundamental direction of the project changes. Completing phases or making minor updates does not touch VISION.md.

---

REQUIREMENTS.md

# [Project Name] — Requirements

## Functional Requirements
- [What the system must do]

## Non-Functional Requirements
- [Performance, reliability, security, scalability expectations]

## Constraints
- [Technical, time, resource, or compliance limits]

## Out of Scope
- [Explicitly what this project does NOT do — prevents scope creep]

---

PHASES.md

# [Project Name] — Phases

> Living document. Phases are stable. Sub-tasks emerge during execution and are added here.
> Complete all sub-tasks from Phase N before starting Phase N+1.

## Phase 1 — [Name]
**Goal:** [What this phase achieves]
**Done when:** [Verifiable condition]

### Tasks
- [ ] [task]

### Emerged Sub-tasks
_(Added during execution. Prioritize and close before Phase 2 starts.)_

---

## Phase 2 — [Name]
...

Rules for PHASES.md:

• Phases can be updated for significant changes — but only if consistent with VISION.md
• Sub-tasks that emerge go into the current phase's "Emerged Sub-tasks" section
• If sub-tasks shift scope so much that VISION.md would need to change — pause and reassess
• The project should not look fundamentally different at Phase 5 than it did at Phase 1

---

WORKFLOW.md

# [Project Name] — Workflow & Tools

## Stack
| Technology | Version | Purpose |
|------------|---------|---------|

## Agents / MCPs
| Tool | Purpose |
|------|---------|

## External Services
| Service | Purpose |
|---------|---------|

## Data Flow
[Brief description of how data moves through the system]

---

Step 5 — Confirm and Lock

After all four files are generated:

1. Present a summary:

   "Here's what we've defined: [2-3 sentences]. VISION.md is now the anchor for this project. PHASES.md is a living document — update it as sub-tasks emerge, but keep it tied to the vision."

2. Ask: "Does this look right? Any changes before we lock the vision?"

3. If changes needed — update the specific file only. Do not regenerate everything.

4. Once approved — vision is locked. Future sessions should read VISION.md first.

---

Critical Rules

• Context first — never ask what you already know from conversation or existing files
• One question at a time — batching questions gets shallow answers
• VISION.md is the anchor — phases and requirements serve it, not the other way around
• "Done when" must be verifiable — "it works" is not an answer
• context7 for versions only at this stage — full docs come during development
• Keep PHASES.md simple — phases are stable, sub-tasks are the flexible part
• Out of Scope section is mandatory — prevents the project from drifting