# Write Project Vision Handoff

> Create implementation-ready project handoff documents from planning context. Use when the user asks to "write a vision handoff", "create a seed document", "prepare this for a coding agent", "turn this plan into VISION.md", or transfer a planned system to an implementation agent. Produces VISION.md and FLOWCHARTS.md plus only directly useful supplementary docs.

- Skill: `ariaxhan/write-project-vision-handoff` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ariaxhan/write-project-vision-handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ariaxhan/write-project-vision-handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ariaxhan (https://skillmd.com/u/ariaxhan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ariaxhan/write-project-vision-handoff

---


# Write Project Vision Handoff

Turn planning context into documents a coding agent can build from without seeing the original conversation.

You are a planner, not the implementer. Capture intent, constraints, decisions, rejected alternatives, and success criteria. Defer exact code structure and implementation choices unless the user explicitly decided them.

## 1. Gather the source context

Read the conversation, notes, brief, screenshots, or spec the user supplied. Extract:

- Explicit decisions
- Rejected alternatives
- Hard constraints and anti-requirements
- User intent signals, including repeated frustrations or preferences
- Edge cases and failure modes already discussed
- Success criteria and launch boundaries

If the source is thin, write the missing assumptions as open questions instead of inventing facts.

## 2. Separate audiences

Write two different documents:

| Document | Audience | Purpose |
|---|---|---|
| `VISION.md` | Coding agent | Dense source of truth: what, why, constraints, decisions, task |
| `FLOWCHARTS.md` | Human reader | Plain-English architecture explanation with diagrams and glossary |

Do not duplicate sections between them. `VISION.md` carries rationale. `FLOWCHARTS.md` carries comprehension.

## 3. Write `VISION.md`

Include:

- What this is
- The problem
- The solution
- Key decisions with rationale and rejected alternatives
- Design constraints
- Anti-requirements
- Planning considerations
- Success criteria
- The coding agent's task

Rules:

- No code or pseudocode.
- No file trees unless already decided.
- No library/framework prescriptions unless already decided.
- Preserve user quotes when they capture intent better than a summary.

## 4. Write `FLOWCHARTS.md`

Include:

- Core concept in simple language
- Glossary for technical/domain terms
- ASCII flow diagram
- Scenario walkthroughs
- Component breakdown
- Questions to verify understanding

Every technical term gets a plain-English definition. Prefer diagrams over paragraphs.

## 5. Add supplementary docs only when needed

Allowed:

- `DECISIONS.md` for many complex tradeoffs
- `CONSTRAINTS.md` for unusual technical or business limits
- `PRIOR_ART.md` for existing systems the plan references
- `GLOSSARY.md` when domain vocabulary is heavy

Do not create README, installation docs, changelog, or implementation guides.

## 6. Validate the handoff

Before finishing, check:

- Could a coding agent build from this without the original conversation?
- Are all decisions and rejected alternatives captured?
- Are constraints sourced and not invented?
- Are success criteria observable?
- Could a non-technical person understand `FLOWCHARTS.md`?
- Is there zero meaningful overlap between the two documents?

Use `reference/templates-and-examples.md` for templates and examples when writing the files.