The Problem

Most repositories accumulate implicit values through hundreds of merged PRs and rejected features, but never write them down. Every new contributor or coding agent re-litigates the same decisions from scratch. Writing a VISION.md from memory produces generic engineering platitudes, not the actual trade-offs the project has already made.

What This Does

vision is an Agent Skill that mines a repository's actual history—merged PRs via gh or gh-axi, falling back to default-branch commit history—and drafts a VISION.md as a testable acceptance policy. Every principle must cite real commits; generic virtues are rejected. The skill then generates 8-12 fault-line hypotheticals (tempting off-mission features, principle collisions) and presents them on an interactive review board.

The review surface is a styled HTML template (skills/vision/assets/review-template.html with review.css) that the agent fills rather than rewrites. Verdicts and reasoning fold back into the draft with traced edits until you approve the final VISION.md plus an answers record.

How It Is Wired

The entry point is skills/vision/SKILL.md, which defines the slash command /vision (or /vision owner/repo). Execution flow:

  1. Learn the pattern — reads exemplar visions and the review template.
  2. Delta mode — if a VISION.md exists, compares against it as baseline.
  3. Mine evidence — runs gh or gh-axi for merged PRs; falls back to git log on the default branch. Produces an evidence sheet.
  4. Draft — builds identity, principles, non-goals, and aligns/resists test cases.
  5. Hypotheticals — generates 8-12 steelmanned proposals.
  6. Review board — launches npx -y lavish-axi to serve the HTML board; card-stack verdicts drive traced edits until approval.

The skill touches the filesystem only for reading git history and writing the final VISION.md + answers record. The only external dependency is lavish-axi, launched directly via npx; a blocker is reported only if that launch fails. No host-specific agent tools are required.

The wiring for this repo is simple: 6 files, no module graph, no cycles. The SKILL.md is the hub everything routes through, and it carries the widest blast radius—any change to the skill's behavior lives there.

How To Use It

Setup (from README, verbatim):

npx skills add kunchenguid/vision -g

Running it: inside the target repo, invoke /vision or /vision owner/repo. Natural language also works: "help me write a VISION.md for this project."

Requirements: read access to the repo and its history. No environment variables or config files are documented—the skill reads what it needs from the repo itself. The review board needs no install; npx -y lavish-axi handles it.

Real-World Use

For a team onboarding new contributors or coding agents: run /vision against the repo, answer the hypotheticals on the review board, commit the resulting VISION.md. Future agents read it as an acceptance policy before proposing changes. The README points to firstmate's VISION.md as a production example produced by this exact process.

Code Health & Issues

Measured analysis (static, not opinion):

  • Med/SDLC — No test files detected; untested code paths, repository-wide.
  • Med/SDLC — No CI/CD pipeline; no automated build/test gate.

The repo has a license (MIT) and no committed secrets. No lockfile is present. The skills directory is small enough that the missing tests are a moderate concern—the logic lives in the SKILL.md prompt and the HTML template, neither of which is easily unit-testable as-is.

The Bottom Line

A well-scoped tool for a real problem: converting unstated project values into a testable document. The evidence-over-vibes constraint is the right call, and the refusal to invent values when history is unreadable is honest. The lack of tests and CI is acceptable for a prompt-and-template package, but the SKILL.md logic will be hard to validate as it grows. Teams already using Agent Skills and gh will get value immediately; others face a setup cost that the README does not fully amortize.