vision/README.md

# Vision (Optional)

This directory is for **project philosophy** — the enduring "why" that persists across all features.

**Most projects don't need this directory.** Delete it if:
- The project is a tool with obvious purpose
- Discovery docs capture your "why" sufficiently
- The project is < 6 months
- You're the only contributor

## When to Use This Directory

Create vision docs when:
- The project IS a methodology (the "why" matters as much as the "what")
- Multiple contributors need philosophical alignment
- The project will evolve over years
- You find yourself repeating the same principles across discovery docs

## Vision vs Discovery

| Vision | Discovery |
|--------|-----------|
| Enduring project philosophy | Feature-specific validation |
| Persists across all features | Per-feature taste capture |
| "Why does this project exist?" | "Why build this feature?" |
| Example: framework principles | Example: feature PR/FAQ |

## What Goes Here

- `VISION.md` — Project philosophy, principles, north star
- `ROADMAP.md` — Outcome-based roadmap (Now/Next/Later)
- Design philosophy documents

## Creating Vision Docs

Use the `strategy` skill for structured vision documents:

```
skill({ name: "strategy" })
```

Or create a lightweight `VISION.md` manually with:
- One-sentence purpose
- 2-3 paragraphs of enduring principles
- Bulleted list of core beliefs

## Example Projects

| Project | Has Vision? | Why |
|---------|-------------|-----|
| `agentic-settings` | Yes | Framework — the "why" IS the product |
| `prompt-recipes` | No | Tool — purpose is self-evident |