kunchenguid/vision: an Agent Skill that turns your repo history into a testable VISION.md

The problem vision solves: values that exist but were never written down

Most repositories carry a set of decisions that never made it into a document. The README puts it as the two hundred PRs you merged, the features you quietly declined, the bug you fixed at the root instead of the symptom. Those choices are real policy, but they live in review threads and commit messages, so every new contributor and every coding agent re-argues them from zero. vision targets exactly that gap: it produces a VISION.md that functions as a testable acceptance policy, not a mission statement. The intended audience is a maintainer with enough history that patterns are visible, and enough conviction that some features should be refused. The README frames the guiding question as what your project refuses to become, which tells you the output is expected to contain non-goals, not just aspirations.

How the skill mines evidence from merged PRs and commit history

The pipeline in the README runs in stages. First the agent learns the pattern: exemplar visions, anatomy, voice. Then it checks whether a vision already exists, and if one does it switches to delta mode and migrates any answers file. Mining comes next, using repo analysis plus merged PRs or commit history to build an evidence sheet. From that sheet the agent drafts identity, principles, non-goals, and aligns/resisted tests. Then it generates 8-12 fault-line hypotheticals, with both sides steelmanned, and puts them on a review board where verdicts are folded back into the draft until approval. Two constraints stand out. Every principle must cite real merged PRs or commits, and generic engineering virtues are banned, so a principle that cannot point at history should not survive. If the history is unreadable, the README states the skill refuses rather than inventing your values. That refusal is the design's most interesting property: the tool would rather fail than produce a plausible-sounding document with no evidence behind it.

Installing vision with npx skills and running /vision in your repo

The Quick Start gives a global install through the skills package manager. Run this from anywhere, since the -g flag installs globally as the README recommends.

npx skills add kunchenguid/vision -g

After that, invoke the skill from inside the target repository. The slash form with no argument uses the repo you are in, and the argument form targets another one.

/vision
# or: /vision owner/repo

Natural language also works: the README lists "help me write a VISION.md for this project" as an equivalent trigger, and says the agent should auto-invoke when asked to write, refine, or stress-test a project vision or contribution-acceptance criteria. What you should see is a review board, launched through npx -y lavish-axi, with your latest draft visible and hypotheticals dealt one at a time from a stack of cards. A verdict flips the card and reveals the next one. The board needs no separate install; the README says a blocker is reported only if the launch itself fails. For contributors working from a checkout, the development section gives a discovery smoke test and a local install.

npx skills add ./ -l
npx skills add ./ -g -y

The review board, the card stack, and why transcripts stay ephemeral

The review surface is a deliberate design choice, not a generic UI. The package ships review.css and review-template.html under skills/vision/assets/, and the README is explicit that agents fill slots and never restyle. The stated look is black ink on white paper set like literature, with the full latest draft always visible while hypotheticals arrive one at a time from a stack. This matters because a vision document is judged on whether it changes a decision, and a wall of simultaneous questions invites shallow answers. The other half of the design is what does not get committed: board transcripts stay ephemeral and are never committed next to the vision. The reasoning from each verdict is reflected in the writing instead, so VISION.md remains the single alignment surface a reviewer reads. That separation is a trade-off worth naming. You lose the audit trail of who answered what, and you keep a repository that contains one policy file rather than a folder of deliberation.

What vision needs from your repository before it will work

The requirements are narrow but real. The skill needs read access to the repo and its history, preferring merged PRs through gh or gh-axi when accessible and falling back to default-branch git commit history otherwise. That fallback is the important clause: if your team squash-merges with meaningful messages, the commit path can carry the evidence. If your history is a chain of "fix" and "wip" commits, the evidence sheet will be thin, and the README's refusal behaviour becomes the likely outcome. The skill claims no host-specific agent tools, so any harness should run it, though that is a claim in the README rather than something verified here. The review board depends on lavish-axi launched through npx -y, which means the machine running the agent needs network access to fetch it. There is no mention of a hosted service, an account, or a stored credential, and the package layout shows only SKILL.md plus two asset files, so the whole contract lives in one self-contained markdown file.

Where vision is the wrong tool

The failure mode is a repository with no readable history. A project that is three weeks old, or one where decisions were made in chat and never landed as commits, gives the skill nothing to cite, and by its own rules it should refuse rather than write generic principles. That refusal is correct behaviour and still leaves you without a document. A second mismatch is intent. If you want a forward-looking statement about where the product is going, vision is aimed the other way: it mines what you already did and converts it into accept/resist criteria, so a team with no merged decisions to point at gets little. A third case is process tolerance. The workflow demands that a human answer 8-12 hypotheticals with both sides steelmanned, and the README notes that if your answer is predictable the question gets replaced. Anyone hoping to generate a VISION.md unattended, without sitting through the board, is working against the design rather than with it.

vision compared with writing a VISION.md by hand

The honest alternative is a maintainer writing VISION.md directly, and the difference is not the file format. A hand-written vision is usually produced in one sitting from memory, which makes it fast and also makes it aspirational: principles get stated as values like simplicity or quality with nothing behind them. vision inverts the order. Evidence is collected first from merged PRs or commits, principles must cite it, and generic engineering virtues are banned, so the draft is constrained by what the repository actually did. The second difference is adversarial testing. A hand-written document is rarely challenged on the day it is written; vision generates 8-12 fault-line hypotheticals, tempting-but-off-mission features and principle collisions, and folds the reasoning from your verdicts back into the draft. The cost of that rigor is time and a dependency on history quality. A solo maintainer of a young project will finish faster by hand and get a document that is honest about being aspirational. The README points to firstmate's VISION.md as an example of the output, which is the right place to look before deciding whether the process is worth it for your repo.

Licence, maintenance, and upgrade cost

The repository is MIT licensed, which permits use, modification, and redistribution provided the copyright notice and permission notice are preserved; that is a summary of the licence identifier and not legal advice, so read LICENSE for the actual terms. The last push to main was on 2026-09-02, and the repository is not archived, so there is recent activity, though no releases are listed, which means there is no versioned changelog to read before upgrading. Upgrade cost is low by construction: the package is a skill directory with SKILL.md and two assets, installed through npx skills, so refreshing it is a reinstall rather than a migration. The one thing to watch is the review surface. Because agents are told to fill the board template and never restyle it, a future change to review.css or review-template.html is a change to every board you open, and any local fork of those files will drift from the shipped version. If you have already produced a VISION.md, the README describes delta mode for repositories with an existing vision, which is the path to use when re-running the skill rather than starting over.

Editorial conclusion

Adopt vision if your repository has a long merge and commit history that already encodes decisions, and you want those decisions written down as an accept/resist test rather than a mission statement. Skip it if the repo is new, history is thin, or you want a brainstormed vision doc with no evidence requirement, because the skill is designed to refuse rather than invent values. Before installing, check that gh or gh-axi can read merged PRs, or that default-branch commit history is readable enough to cite, and confirm you are willing to answer 8-12 hypotheticals on the review board. The deliverable is one file, VISION.md, and the process is done when that file alone can settle an accept/resist question.

Frequently asked questions

Official sources

1. Issues
2. kunchenguid/vision on GitHub
3. License: MIT
4. README