Writing: read docs/skills/shared/writing-rule.md before you write a durable artifact.

/tech-vision — Interactive Architecture Vision Author

Walks the operator through the existing templates/architecture/vision.md (shipped in #224) section by section — instead of leaving the operator staring at an empty template — so the load-bearing sections (Anti-scope, Current-vs-Target, Migration path) actually get filled in honestly rather than left as aspirational stubs.

The output is a fully populated vision.md ready to commit. Markdown-only — the single graphical element (target-state C4 L1) renders inline via Mermaid on GitHub. No HTML, no SVG, no build step.

Why /tech-vision and not /vision? In a multi-stakeholder portfolio the word "vision" collides with product / company vision documents that Heads of Product and CEOs author in a different shape. The tech- prefix disambiguates this skill as the technical / architecture vision author. The output filename (vision.md) and template path (templates/architecture/vision.md) stay unchanged — only the slash-command carries the prefix.

Design rationale + sub-decisions: AgDR-0028.

Skill	Role
/tech-vision (this skill)	Authors the target-state + migration path — north-star architecture, prose + bulleted horizons
/c4	Static topology — current-state system + container diagrams
/dfd	Data flow — trust boundaries + data classifications (input to /threat-model)
/sequence (template)	Request-flow walkthroughs (auth handshake, payment flow)

Path resolution

Read the registry path via portfolio_registry, the per-project docs dir via portfolio_projects_dir, and the template path via portfolio_resolve_template — all from .claude/hooks/_lib-portfolio-paths.sh. Source the helper at the top of any bash block that touches those paths:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
projects_dir=$(portfolio_projects_dir)
template=$(portfolio_resolve_template architecture/vision.md)

Defaults match today's single-fork layout (./projects, ./templates/architecture/vision.md). Adopters in split-portfolio mode override the portfolio.{registry, projects_dir} keys in .claude/project-config.json and may drop a custom template at <private_repo>/custom-templates/architecture/vision.md — the helper resolves whichever mode they're in. See docs/multi-project.md and templates/README.md (custom-templates layer).

Write targets (see me2resh/apexyard#373 + #443): paths documented as projects/<name>/X in this skill are canonical adopter-facing forms — implement them in bash as "${projects_dir}/<name>/X". Never construct from "${PWD}/projects/...", "$(git rev-parse --show-toplevel)/projects/...", or a literal ./projects/... — those break in split-portfolio v2 mode where projects_dir resolves to a sibling repo.

REQUIRED per-block preamble (see #443): Claude executes each bash block as a separate shell invocation. The projects_dir assignment from the Path resolution section above does NOT carry into later blocks. Every bash block that writes to a projects/<name>/X path MUST start with this three-line preamble so it's self-contained:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
projects_dir=$(portfolio_projects_dir)
# ... now write to "${projects_dir}/<name>/X"

The Path resolution section's example sources the helper once for documentation purposes; it does not absolve later blocks from sourcing it themselves. Treat each bash fence as a fresh process.

Usage

/tech-vision                       # interactive — asks which project (or framework-wide)
/tech-vision billing-api           # registered project — writes to projects/billing-api/architecture/vision.md
/tech-vision .                     # treat cwd as the project root
/tech-vision --framework           # framework-wide vision — writes to docs/architecture/vision.md

Re-running on an existing vision.md OFFERS (default-no) to overwrite — same UX as /c4, /extract-features, /dfd. Accept-no preserves the existing file; accept-yes seeds each section's prompt with the existing content as the default, so the operator can refresh a single section without rewriting the whole vision.

Output location

Where the file lands depends on where the skill is invoked from and what argument is passed — same split as /c4:

Invoked from	Arg	Output
Ops fork root	<name> (registered project)	projects/<name>/architecture/vision.md
Ops fork root	--framework	docs/architecture/vision.md
workspace/<name>/ (project clone)	none	projects/<name>/architecture/vision.md (resolved via the ops fork — vision is the ops-fork view of where the project's architecture is going)
Anywhere	.	Treat cwd as the project; write to docs/architecture/vision.md inside the cwd

The split mirrors the existing convention from docs/multi-project.md § "Architecture diagrams".

Process

Use AskUserQuestion for every operator option menu in this skill. Follow .claude/rules/reporting-style.md § Operator choices. Preserve multiple selections where the menu permits them. Split menus with more than four options into sequential wizard questions. Keep single yes/no and ticket confirmation prompts as written. The prose menus below are fallbacks only when the harness lacks AskUserQuestion.

1. Resolve the target + load the template

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"

template=$(portfolio_resolve_template architecture/vision.md)
if [ -z "$template" ] || [ ! -f "$template" ]; then
  echo "BLOCKED: cannot resolve architecture/vision.md template" >&2
  exit 1
fi

# Resolve the project + output path per the table above:
# - If --framework: out=<ops_root>/docs/architecture/vision.md
# - Else if arg is .: out=<cwd>/docs/architecture/vision.md
# - Else if arg is a registered project name: out=<projects_dir>/<name>/architecture/vision.md
# - Else if no arg + cwd inside workspace/<name>/: derive <name>, same as above
# - Else (no arg + cwd is ops fork root): ask the user

If the resolved output file already exists, use AskUserQuestion for keep, overwrite, or refresh. Recommend keep first. Use the prompt below only when the harness lacks the tool:

projects/<name>/architecture/vision.md already exists (last written {date}).

  (1) keep existing (Recommended) — exit without changes
  (2) refresh — start the interview with existing content as defaults
  (3) overwrite — start a fresh interview

> 

On refresh: parse existing file sections and use each section as an interview default. On keep: exit. On overwrite: ignore existing content and start step 2 with empty defaults.

2. Read the template structure

Parse the resolved template (portfolio_resolve_template architecture/vision.md) to discover its sections. The framework default has seven, in order:

#	Section	Interview shape
1	Scope	Single one-sentence answer
2	Principles	Repeated prompt: "principle N (or done)" — 5–10 items, skill suggests stopping at 5 unless operator has strong reason for more
3	Target-state architecture	Multi-line: paste Mermaid C4 L1, OR accept template's placeholder, OR ask operator to run /c4 <project> --level=1 first and paste the output
4	Current state vs target state	Repeated row prompt: dimension / today / target / gap — 4–8 rows, skill suggests dimensions (Data layer, Auth, Deployment, Observability, Async messaging, Frontend, Secrets management) from the template's worked example as starters
5	Migration path	Repeated row prompt: quarter / milestone / owner / "done when" — 3–5 milestones
6	Things we explicitly chose NOT to build (anti-scope)	Repeated prompt: anti-scope item + rationale + "reconsider when" trigger — at least 2 required, skill emphasises this is the load-bearing section
7	Review cadence	Default quarterly, operator can override (single answer)

If the operator has overridden the template at <private_repo>/custom-templates/architecture/vision.md, the skill reads that file's sections instead. The interview follows whatever sections the resolved template defines — the section list is not hardcoded.

Discovery: walk the template's ^## headings in order; each heading is one interview section. Use the heading text verbatim in the prompts.

3. Run the interview — section by section, per-section confirm

For each section:

1. Show the section heading and a one-line context (extracted from the template's section intro paragraph, trimmed to one line).

2. Prompt for the section's content. The prompt shape depends on whether the section is single-answer, multi-line, or repeated-row (per the table above). For sections with worked examples in the template, surface 1–2 examples as starting suggestions — never as the answer.

3. Show the assembled section as it will appear in the final file.

4. Confirm:

   Section "Principles" — looks good?
     (y) accept and continue to next section
     (e) edit — restart this section
     (s) skip — leave section as template default (NOT recommended for Anti-scope or Migration path)
     (q) quit — don't write anything
   > 
   

If the operator picks s on Anti-scope or Migration path, re-prompt with a stronger warning:

Anti-scope is the load-bearing section that prevents the vision from rotting
into aspirational filler. Skipping it produces a half-filled-in stub of the
exact kind /tech-vision exists to prevent.

Really skip? [y/N]

Default N. Other sections can be skipped without warning (Scope, Principles, Review cadence have sane template defaults).

4. Show the assembled doc + final confirm

After all sections, show the fully assembled vision as it will be written. Final prompt:

Vision assembled — {N} sections, {M} principles, {K} anti-scope items, {Q} migration milestones.

  (y) write to <output-path>
  (e) restart at section: 1 / 2 / 3 / 4 / 5 / 6 / 7  → re-prompt for that section
  (q) quit — don't write
> 

5. Write the file + lint the Mermaid

Write the assembled markdown to the resolved output path. The Target-state section may contain a ```mermaid C4 L1 block (pasted by the operator or generated via /c4). Validate every Mermaid block in the file via the shared lint:

SKILL_DIR="$(dirname "$(realpath "$0")")"
"$SKILL_DIR/lint.sh" "$vision_out" || lint_rc=$?

Wraps _lib-mermaid-lint.sh — graceful-degrades when Node / npx is unavailable (exit 3, advisory only). Exit 1 (parse error) → ask the operator whether to fix the Target-state block by hand or re-run with --skip-lint. Exit 3 → one-line warning, proceed.

End the file with the apexyard-skill footer convention (same as /c4, /dfd, /extract-features):

---

_Generated by `/tech-vision` on YYYY-MM-DD. Re-run quarterly (or after a significant architecture decision) — `/tech-vision <project>` with the `r` (refresh) option preserves the existing content as defaults._

Print a one-line summary:

✓ Vision written: projects/<name>/architecture/vision.md
  Sections: 7 · Principles: 5 · Anti-scope: 3 · Migration milestones: 4
  Reviewed quarterly per § "Review cadence" — next review: {Q+1}

6. Suggest follow-ups

Surface the natural next-steps the operator likely wants:

• C4 current-state diagrams — if no projects/<name>/architecture/{context,container}.md exists, suggest /c4 <project> to capture the as-is system topology (the vision's Target-state section describes where we're going; /c4 documents where we are today).
• Migration ticket for the Q1 milestone — /migration if it touches schema, /feature otherwise.
• AgDRs for any technical decisions implied by the migration path — /decide for each.
• Quarterly review reminder — surface the cadence so the operator knows to re-run /tech-vision <project> (refresh mode) in 3 months.

Rules

1. Operator authors the content; the skill structures the prompts. Never fill in section bodies on the operator's behalf — the worked examples in the template are starting suggestions, not auto-accepted answers.
2. Never auto-overwrite — existing vision.md requires explicit o or r. The file may have been hand-edited; clobbering silently is the worst-case failure.
3. Per-section confirm is mandatory — the operator iterates one section at a time, not by re-running the whole interview.
4. Anti-scope cannot be skipped silently — the second-warning prompt is the load-bearing UX that turns the "stub vision" failure mode into a deliberate decision.
5. Follow the resolved template's section list — do not hardcode the framework default's seven sections. An adopter with a custom template (5 sections, 9 sections) gets an interview that matches their template.
6. Footer signature is mandatory — every generated file ends with the Generated by /tech-vision on YYYY-MM-DD line so future readers know how to refresh it.
7. Markdown-only output — no HTML, no SVG, no JSON sidecar. The vision IS the source of truth.
8. Refuse if no template resolves — portfolio_resolve_template returning empty means the framework default is missing too; stop with a clear error rather than producing an empty file.

When to use this

Trigger	Use /tech-vision?
Quarterly architecture review for a registered project	Yes — re-run with r (refresh) to preserve last quarter's content as defaults
New project just adopted via /handover; need to set north-star architecture	Yes — fresh run, all 7 sections from scratch
Tech Lead onboarding wants to see "what's the target state"	Read the existing projects/<name>/architecture/vision.md — the skill produced it for exactly this reader
Drawing a current-state container diagram	No — use /c4
Drawing a data-flow diagram	No — use /dfd
Recording a single technical decision (library choice, framework upgrade)	No — use /decide (writes an AgDR, much narrower scope)
Multi-team vision (one team's vision feeds another's)	No — out of scope for v1; one vision per system / domain
Product / company vision (audience, market, business goals)	No — /tech-vision is the technical / architecture vision; product vision belongs in a separate PRD / strategy doc

Anti-patterns

• Don't auto-generate vision content from a problem statement — the model doesn't have the operator's architecture context. The skill structures the interview; the operator authors the answers.
• Don't chain /c4 automatically from inside /tech-vision (v1 scope). /c4 produces a current-state diagram; the vision's Target-state section is by definition NOT today's code. Suggest /c4 as a follow-up if no current-state diagram exists; let the operator paste a target-state Mermaid block inline.
• Don't ship without an Anti-scope section. The skill enforces this via the second-warning prompt; the rationale section in the output documents WHY each item was declined and WHEN to reconsider — without those the section is filler.
• Don't treat the vision as a once-and-done artefact. The template includes a Review cadence (default quarterly). Re-run with r (refresh) at each review; preserve content for unchanged sections, update the rest.

Out of scope (v1)

• Chaining /c4 to scaffold the target-state diagram — accept inline Mermaid in v1; chain in a v1.x follow-up if operators ask.
• HTML / SVG / interactive rendering — markdown-only by design.
• A /tech-vision-review companion that re-prompts every section quarterly — the idempotent refresh mode handles this.
• Vision enforcement (Rex checking whether new code matches the vision) — that's a /decide + AgDR concern, not a vision-doc one.
• Multi-team vision composition — one vision per system / domain.
• Vision-doc trend tracking across quarterly reviews — use git log projects/<name>/architecture/vision.md and the AgDR history instead.

---

Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.