// Captures project vision and philosophy through structured interview, producing comprehensive vision documentation and condensed summary. Use before project-planning for new projects or major architectural work requiring design alignment. Ensures blockers and autonomous development can align with project goals.
| name | project-vision |
| description | Captures project vision and philosophy through structured interview, producing comprehensive vision documentation and condensed summary. Use before project-planning for new projects or major architectural work requiring design alignment. Ensures blockers and autonomous development can align with project goals. |
This skill conducts a structured interview to capture comprehensive project vision, philosophy, and design principles. It produces both detailed documentation and a condensed summary embedded in the project's CLAUDE.md file.
Purpose: Establish a "north star" for decision-making that makes architectural choices obvious and enables autonomous agents to resolve blockers without escalation.
Use this skill BEFORE project-planning for:
docs/VISION.md - Comprehensive vision document (~2-5k tokens)CLAUDE.md update - Condensed summary (1 paragraph) with pointer to full docGoal: Extract complete vision through targeted questions across 6 dimensions.
Interview Structure:
Interview Process:
Output: Structured notes covering all 6 dimensions (temp file for next stage)
Goal: Transform interview notes into comprehensive, well-structured vision document.
Deploy Vision Writer sub-agent:
Write comprehensive project vision document.
Context:
- Interview notes: /tmp/vision-[ts]/interview-notes.md
- Project directory: [path]
Output: /tmp/vision-[ts]/VISION-DRAFT.md
Instructions:
1. Read interview notes thoroughly
2. Produce vision document with this structure:
# Project Vision: [Project Name]
## Problem Statement
[1-2 paragraphs: problem, who has it, current solutions, why this is better]
## Users & Use Cases
### Primary Users
[Description of user personas]
### Core Use Cases
1. [Use case 1]: [Description]
2. [Use case 2]: [Description]
...
## Success Criteria
### Definition of Done
[What "complete" means for this project]
### Quality Bar
[Production-ready? Prototype? Research vehicle?]
### Metrics
[How we measure success]
## Design Philosophy
### Guiding Principles
1. **[Principle 1]**: [Why this matters, what it means in practice]
2. **[Principle 2]**: [Explanation]
...
### Key Trade-offs
[Pre-decided trade-offs that resolve common decision points]
### Optimization Target
[When in doubt, we optimize for: X over Y]
## Anti-goals
[Explicitly out of scope - what NOT to do]
- [Anti-goal 1]: [Why not]
- [Anti-goal 2]: [Why not]
## Technical Constraints
[Platform, integration, performance, deployment constraints]
## Decision Framework
[How to make decisions aligned with this vision]
- If [scenario], choose [approach] because [principle]
- Example decision patterns based on philosophy
3. Write clearly and specifically (not vague platitudes)
4. Include concrete examples for abstract principles
5. Make trade-offs explicit (not implicit)
6. Length: 2-5k tokens (comprehensive but not exhaustive)
Return: Summary + file path
Goal: Validate vision quality through three independent review passes.
Deploy 3 concurrent review sub-agents:
Review vision for internal consistency.
Context:
- Vision draft: /tmp/vision-[ts]/VISION-DRAFT.md
Output: /tmp/vision-[ts]/REVIEW-CONSISTENCY.md
Instructions:
1. Read vision document thoroughly
2. Check for contradictions:
- Do principles conflict with each other?
- Do success criteria align with problem statement?
- Do anti-goals contradict stated use cases?
- Do technical constraints conflict with philosophy?
3. Check for completeness:
- Every section substantive (not placeholder)?
- Principles actionable (not vague)?
- Trade-offs explicit?
4. Flag ambiguities:
- Terms used inconsistently?
- Principles too abstract to apply?
- Success criteria not measurable?
Produce report with:
- Contradictions found (with line references)
- Completeness gaps
- Ambiguities requiring clarification
- Recommendation: APPROVED / NEEDS_REVISION
Return: Summary + file path + status
Identify gaps in vision coverage.
Context:
- Vision draft: /tmp/vision-[ts]/VISION-DRAFT.md
Output: /tmp/vision-[ts]/REVIEW-GAPS.md
Instructions:
1. Read vision document
2. Generate follow-up questions for major gaps:
- Missing user personas or use cases?
- Unclear success metrics?
- Principles without examples?
- Important trade-offs not addressed?
- Technical constraints under-specified?
3. Classify gaps:
- CRITICAL: Blocks decision-making
- IMPORTANT: Would improve clarity
- NICE_TO_HAVE: Optional enhancement
Produce report with:
- Follow-up questions by category
- Rationale for each question
- Impact if left unresolved
- Recommendation: APPROVED / NEEDS_INTERVIEW
Return: Summary + file path + status
Review vision for adherence to PRIME DIRECTIVE.
Context:
- Vision draft: /tmp/vision-[ts]/VISION-DRAFT.md
- PRIME DIRECTIVE: Read the project CLAUDE.md (Maximal Simplicity Policy)
Output: /tmp/vision-[ts]/REVIEW-PRIME-DIRECTIVE.md
Instructions:
1. Read the project CLAUDE.md PRIME DIRECTIVE section
2. Read vision document
3. Evaluate alignment:
- Does philosophy emphasize simplicity over complexity?
- Are principles about separation of concerns vs complecting?
- Do trade-offs favor simple over clever?
- Does decision framework guide toward simplicity?
4. Check for red flags:
- Encouraging premature abstraction?
- Conflating concerns in design principles?
- Optimizing for "flexibility" over directness?
- Framework-style patterns over simple solutions?
Produce report with:
- Alignment score: STRONG / MODERATE / WEAK
- Areas of strong alignment
- Areas of concern
- Suggested principle additions/modifications
- Recommendation: APPROVED / NEEDS_REVISION
Return: Summary + file path + status
Parallelism: Deploy all reviewers in single message via multiple Task calls.
Gate Logic (based on sub-agent reports):
Goal: Write final vision document and embed summary in CLAUDE.md.
Process:
# Incorporate review feedback
# Write to: docs/VISION.md
Create 1-paragraph summary for CLAUDE.md:
Example:
## Project Vision
my-project is a lightweight task runner emphasizing simplicity and composability. Core philosophy: prefer simple, separated concerns over clever abstractions; optimize for debuggability and comprehension over performance; make the straightforward path obvious. When in doubt, choose the approach with fewer moving parts. See [docs/VISION.md](docs/VISION.md) for complete vision and decision framework.
If CLAUDE.md exists in project:
## Project Vision section after project descriptionIf no CLAUDE.md:
git add docs/VISION.md CLAUDE.md
git commit -m "docs: capture project vision and philosophy
- Comprehensive vision document (problem, users, philosophy, constraints)
- Decision framework for autonomous development
- Embedded summary in CLAUDE.md"
Report to user:
docs/VISION.mdResearch sub-agents should:
CLAUDE.md (gets condensed vision automatically)docs/VISION.md for detailed contextPrior art research synthesis should:
Plan auditors should:
Implementation agents should:
Main agent:
Sub-agents:
Temp structure:
/tmp/vision-[timestamp]/
├── interview-notes.md # Structured interview output
├── VISION-DRAFT.md # Initial draft
├── REVIEW-*.md # Review reports
└── VISION-FINAL.md # Revised version (if needed)
Vision document is complete when:
## Project Vision
my-saas is a B2B analytics platform for small businesses, prioritizing rapid iteration and customer learning over scale. Core philosophy: ship early, learn from users, consolidate based on evidence; optimize for time-to-insight over performance; embrace manual processes until automation pays for itself. Pre-alpha risk tolerance allows breaking changes. When facing build-vs-buy, prefer battle-tested external services over custom code. See [docs/VISION.md](docs/VISION.md) for complete vision, use cases, and decision framework.
This gives autonomous agents immediate context while keeping CLAUDE.md scannable.
Reviews completed work by exploring features as a user would, finding gaps between intent and implementation, writing failing tests for real issues, and creating tickets for genuine problems. Runs automatically after all planned tasks complete.
Autonomously discovers ready tasks from Tickets, executes them with Research → Implement → Verify cycles, continuing with related work while context remains healthy - invoke directly without specifying a task
Creates new Claude Code agent skills with proper structure, frontmatter, and best practices. Use when the user wants to create a new skill, add capabilities, or extend Claude with domain-specific expertise.
Autonomously investigates REQUIRES-INVESTIGATION tasks through deep parallel research (internal and external), synthesizes findings, and either resolves with an actionable task or escalates to HUMAN-TASK when genuine human judgment is needed. Use when autonomous-development creates investigation tasks.
Translates finalized feature plans into comprehensive tickets for autonomous development. Use after project-planning and reviewing-plans sessions are complete. Creates self-contained tickets with inlined requirements and verification commands.
Orchestrates comprehensive feature planning through autonomous research phases and map-reduce cycles. Researches codebase first to understand current state, only interviews user for human judgment questions, then runs research waves after each interview round. Produces detailed implementation plans with executable verification commands.