User Story

As a Tech Lead authoring the company's (or a project's) technical vision document, I want a /vision skill that walks me through the existing templates/architecture/vision.md (shipped in #226) section by section — instead of staring at the empty template and copy-pasting boilerplate — so the resulting doc actually gets filled in honestly rather than left as an aspirational stub.

Acceptance Criteria

Skill

• New /vision slash command at .claude/skills/vision/SKILL.md
• Uses the override resolver from #A — checks custom-templates/architecture/vision.md first, falls back to templates/architecture/vision.md
• Walks the operator through filling each section interactively (one section at a time, mirroring the per-section flow used by /decide, /feature, /spike):
  • Scope — what system or domain this vision covers (one sentence)
  • Principles — 5-10 architectural principles, prompted one at a time. Skill suggests the operator stop at 5 unless they have strong reason for more
  • Target-state architecture — Mermaid C4 L1 diagram. Skill offers to call into /c4 to scaffold the diagram, or accept inline markdown if the operator already has one
  • Current state vs target state — table with Today / Target / Gap columns. Skill prompts for 4-8 dimensions (data layer, auth, deployment, observability, etc.)
  • Migration path — multi-quarter milestones. Skill prompts for 3-5 milestones with explicit "by Qx, X moves to Y" sentences
  • Things we explicitly chose NOT to build (anti-scope) — prompted; the skill emphasises this is the load-bearing section, not optional
  • Review cadence — default quarterly, operator can override
• Persistence:
  • Project-scoped invocation (cwd inside workspace/<project>/ or argument --project <name>): writes to <projects_dir>/<project>/architecture/vision.md
  • Framework-scoped invocation (cwd at ops fork root, no project arg): writes to <ops_root>/docs/architecture/vision.md
• Confirmation step before writing: shows the assembled vision doc, accepts yes/edit X/cancel
• Idempotence: re-running on an existing vision doc OFFERS to update specific sections (default-no on each), doesn't blow away the existing content

/c4 integration

• If the operator picks the "scaffold via /c4" option in the Target-state section, /vision invokes /c4 with the project context, captures the resulting diagram, and embeds it inline in the vision doc

Single-fork mode + no-override behaviour

• Adopters without a portfolio block fall straight through to templates/architecture/vision.md. Skill works identically.

Tests

• Smoke test on /vision: produces a valid markdown file with all sections populated
• Override-resolution test: custom-templates/architecture/vision.md present → skill output reflects the custom shape
• Idempotence test: re-run on existing vision doc → preserves existing content for sections not explicitly updated

Docs

• CLAUDE.md ## Templates table cross-references /vision
• templates/architecture/vision.md (already shipped in feat(#224): add architecture vision + DFD + sequence templates #226) gains a one-line note pointing at /vision as the recommended authoring path

Design Notes

Why a skill, not just hand-edit the template. The vision template is the artefact most likely to be left as a half-filled-in stub. The "current vs target" table and the "anti-scope" section are the load-bearing parts; without a skill prompting for them explicitly, operators tend to ship vision docs that are pretty pictures + one-sentence principles + nothing actionable. The skill's job is to force the hard sections to actually get filled in.

Why /c4 integration matters. The Target-state section calls for a Mermaid C4 L1. Operators often skip it because authoring Mermaid feels expensive. Wiring /c4 in as an offered substep removes the friction; even an auto-generated diagram is a starting point.

Vision scope: framework-wide vs project-specific. Both shapes are valid:

• A /vision for the whole framework lives at <ops_root>/docs/architecture/vision.md (rare; for the framework's own technical direction)
• A /vision for a managed project lives at <projects_dir>/<project>/architecture/vision.md (common; per-project)

The skill detects which based on cwd / --project arg.

Depends on #A. Custom-templates override resolver lands first.

Out of Scope

• Multi-team vision composition (one team's vision feeding another's; out of scope)
• Vision-doc trend tracking across quarterly reviews (use git log + AgDRs instead)
• Vision-doc enforcement (Rex doesn't check whether code matches the vision; that's a /decide / AgDR concern, not a vision-doc one)
• A /vision-review companion that re-prompts every section quarterly (the manual idempotent re-run from the AC above is sufficient for v1)

Effort Estimate

TBD — likely 0.5 day for the skill + tests once #A's resolver exists. Reuses the section-by-section flow pattern from /decide etc.