!${CLAUDE_PLUGIN_ROOT}/scripts/skill-preflight.sh vision 2>&1 || true

@.claude/shirabe-extensions/vision.md @.claude/shirabe-extensions/vision.local.md

Vision Documents

Vision documents capture WHY a project or organization should exist -- the core thesis, audience, value proposition, org fit, and success criteria. They sit at the head of the strategic chain -- VISION -> STRATEGY -> ROADMAP -- and are the strategic foundation that justifies writing requirements in the first place.

A VISION's immediate downstream neighbour is a STRATEGY, and that is the only artifact type its Downstream Artifacts section lists. The chain links one level at a time so a reader walking it hits every altitude in order; the PRDs and designs under a VISION are reached through its STRATEGY and that STRATEGY's ROADMAP, not linked directly. See references/vision-format.md for the full rule.

Writing style: Read skills/writing-style/SKILL.md for guidance.

Artifact Lifecycle

Lifecycle: Durable. Stays in docs/visions/ after completion.

VISION is durable because the long-term thesis a project commits to stays in the audit trail. Future readers asking why a project exists at all need the VISION to remain in place even as the project evolves.

Vision Format

See references/vision-format.md for the full format specification: frontmatter schema, required and optional sections, visibility-gated sections, section matrix, content boundaries, lifecycle states, validation rules, and quality guidance. Load it during Phases 3 and 4.

File Location

Vision documents live at docs/visions/VISION-<topic>.md (kebab-case). No directory movement until Sunset, which moves files to docs/visions/sunset/. Stable paths keep cross-references durable and git blame readable.

Repo Visibility

Before writing content, detect visibility from CLAUDE.md (## Repo Visibility: Public|Private). If not found, infer from repo path (private/ -> Private, public/ -> Public; default to Private). Load the appropriate content governance skill:

• Private repos: Read skills/private-content/SKILL.md
• Public repos: Read skills/public-content/SKILL.md

Public VISIONs must not include Competitive Positioning or Resource Implications sections, and must not reference private artifacts.

Creating a Vision Document

When invoked as /vision, this skill drives a structured creation workflow that scopes the thesis conversationally, fans out research agents, drafts the VISION with section-level review, and validates through jury review.

Unlike an explore workflow (which is open-ended and can produce any artifact type), /vision always produces a VISION document. Use /vision when you know you need strategic justification. Use an explore workflow when you don't know what artifact type you need yet.

Input Modes

From $ARGUMENTS:

1. Empty -- ask the user what project or org they want to define a vision for
2. Path to existing VISION with lifecycle verb (accept, activate, sunset) -- execute the lifecycle transition via shirabe transition <vision-path> <status> (Sunset optionally takes --superseded-by <path>)
3. Anything else -- use as the starting topic for Phase 1 scoping

Standalone Entry

/vision works standalone and as a chain child of /charter. No skill hands /vision a pre-populated scope file: /charter invokes /vision directly and lets this skill's own Phase 1 do the scoping, and the router routes to /charter rather than here. There is no handoff to detect.

On startup, check for key work/scope.md in vision-<topic> anyway. It is what this skill's own Phase 1 writes, so finding one means an earlier run got through scoping and stopped before Phase 2 finished. Skip Phase 1 and resume at Phase 2 against it -- the scope key already holds the problem statement and research leads. /charter's resume ladder routes a partial run back into /vision the same way, through skill-session.sh has-work vision <topic> — a live session holding any work/ key.

If it does not exist, start from Phase 1.

Session and Keys

/vision keeps its working state as keys in its own koto session, vision-<topic>, following ${CLAUDE_PLUGIN_ROOT}/references/skill-session-convention.md. It writes no file to the staging folder, chained or direct. Its first act, once the topic is known (from the argument, or the <topic> in a path argument's file name) and before Context Resolution or the resume rows below, opens the session and records whether it runs under a parent:

"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" open vision <topic>
"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" adopt vision <topic>

open attaches to a live vision-<topic> (an interrupted run, whose keys the resume rows read), replaces a finished one (a fresh run), or creates it. Any non-zero exit from either command stops the run with the script's message: 127 or 69 means koto is missing or too old, and the skill never falls back to files. adopt exiting 3 is the two-parents case below.

Keys are read and written with koto against vision-<topic>: koto context exists vision-<topic> <key> tests one (exit 0 present, 1 absent), koto context get vision-<topic> <key> prints it, koto context add vision-<topic> <key> stores the content given on stdin (the whole content: to change part of it, get the key, edit it, and add it back), koto context list vision-<topic> --prefix <prefix> lists keys, and koto context remove vision-<topic> <key> removes one. Research and reviewer agents never write keys: each phase that spawns them pins every output to a file in a skill-session.sh scratch directory and ingests it.

Closing. A direct run closes its session when it finishes: "${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" close vision-<topic> done at the end of Phase 4, or close vision-<topic> abandoned after a discard. Under a parent /vision never closes its own session: the parent closes it at its own exit (skill-session.sh close-children), and the keys stay readable until then.

Context Resolution

Execution mode: check $ARGUMENTS for --auto or --interactive flags, then CLAUDE.md ## Execution Mode: header (default: interactive). Also parse --max-rounds=N (default: 2 for vision's discover loop). In --auto mode, follow decision-protocol conventions -- make decisions based on evidence rather than blocking on user input. Track decisions in key work/decisions.md in vision-<topic>.

Detect visibility (Private/Public) from CLAUDE.md or repo path. Infer from private/ or public/ in path if not explicit. Default to Private if unknown -- restricting is easier to undo than oversharing.

Log: Drafting vision with [Private|Public] visibility...

Workflow Phases

Phase 0: SETUP --> Phase 1: SCOPE --> Phase 2: DISCOVER --> Phase 3: DRAFT --> Phase 4: VALIDATE
(branch)          (conversational)   (agents fan out)     (iterative)        (jury review)
                       |                                       ^
                       |                                       |
                       +--- may loop back to DISCOVER or DRAFT-+

Phase 2 agents investigate: audience validation, value proposition clarity, org fit evidence, competitive landscape (private only), and success criteria measurability.

Phase 4 jury focuses on VISION-specific quality: Is the thesis a hypothesis (not a problem statement)? Do success criteria avoid feature-level metrics? Does org fit explain why HERE and not elsewhere? Are non-goals about identity (not scope)?

Resume Logic

dispatch read vision <topic> prints parent=<session>
                                                        -> run under that parent; see ${CLAUDE_PLUGIN_ROOT}/references/fixes/sub-agent-dispatch.md
VISION exists with status "Accepted" or "Active"        -> Offer to revise or start fresh
VISION exists with status "Draft"                       -> Offer to continue from Phase 3
research/phase2_* keys exist in vision-<topic>          -> Resume at Phase 3
work/scope.md key exists in vision-<topic>              -> Resume at Phase 2
On a branch related to the topic                        -> Resume at Phase 1
On main or unrelated branch                             -> Start at Phase 0

The work/scope.md row is a partial-run row, not a handoff row. Its only producer is this skill's own Phase 1, and /charter's ladder relies on that: its row 8 hands a topic back to /vision precisely so this row fires.

Running under a parent. The first row runs "${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" dispatch read vision <topic> with the topic this run works on. A printed parent=<session> line means /vision runs under that parent (scope-<topic> or charter-<topic>), with the parent's upfront decision in the rationale= and suppress_status_aware_prompt= lines; what changes under a parent is in ${CLAUDE_PLUGIN_ROOT}/references/fixes/sub-agent-dispatch.md. Four cases are no match. Three print nothing and exit 0, and the run is a direct one with the rows below unchanged: no parent session, a finished parent session, and a parent whose chain/dispatch key names another child. The fourth, two parent sessions that both name /vision, exits 3: don't pick one and don't run directly; stop and report both sessions, which the script names on stderr, so the author can clear the stale key. Any non-zero exit stops the run with the script's message; open has already stopped a run without koto.

Critical Requirements

• Conversational First: Phase 1 is a dialogue, not a form to fill out
• Research Before Drafting: Don't draft a thesis you haven't investigated
• User Review: Never finalize a VISION the user hasn't reviewed and given feedback on
• Jury Validation: Phase 4 is not optional -- thesis quality, content boundaries, and section guidance compliance all get checked

Execution

Execute phases sequentially by reading the corresponding phase file:

0. Setup: Ensure work happens on a feature branch
   • If already on a branch that matches the topic, skip branch creation
   • If on main or an unrelated branch, create docs/<topic> (kebab-case)
   • If unsure whether the current branch is related, ask the user
1. Scope: Conversational scoping
   • Instructions: references/phases/phase-1-scope.md
   • Skipped when an earlier run's scope key (work/scope.md in vision-<topic>) exists
2. Discover: Parallel research agents investigate leads
   • Instructions: references/phases/phase-2-discover.md
3. Draft: Produce VISION draft and walk through with user
   • Instructions: references/phases/phase-3-draft.md
4. Validate: Jury review and finalization
   • Instructions: references/phases/phase-4-validate.md

Output

Final artifact: docs/visions/VISION-<topic>.md, created in Draft status. After user approval, transition to Accepted via shirabe transition <vision-path> Accepted.

After acceptance, suggest next steps:

Team Shape

/vision's team shape is declared in team.yaml as the machine-readable contract surface. The child layer spawns three reviewer peers at Phase 4 (thesis-quality-reviewer, content-boundary-reviewer, section-guidance-reviewer) to validate the drafted VISION.

See Dispatch Contract for v1 parent-side consumption rules.

Reference Files