⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

vision

kunchenguid@kunchenguid⭐ 348 stars· last commit 2mo ago· 1 open issues

>

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 348 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Your repo has values. They are in the two hundred PRs you merged, the features you quietly declined, the bug you fixed at the root instead of the symptom. They are just not written down - so every contributor, every coding agent, and every future you re-litigates them from scratch.

vision is an Agent Skill that mines what you actually build, drafts a VISION.md as a testable acceptance policy, then stress-tests it with hard hypotheticals - tempting-but-off-mission features, principle collisions, slippery slopes - whose answers only you can give. You answer them on an interactive review board, and the reasoning behind each verdict is reflected in the writing, until VISION.md is sufficient on its own for an accept/resist test.

  • Evidence over vibes - every principle cites real merged PRs or commits; generic engineering virtues are banned. If your history is unreadable, the skill refuses rather than inventing your values.
  • Stress-tested, not brainstormed - 8-12 fault-line hypotheticals per vision, both sides steelmanned; if your answer is predictable, the question gets replaced.
  • A house-style review surface - the package ships a stylesheet and a board template the agent fills rather than rewrites: black ink on white paper set like literature, your full latest draft always visible, hypotheticals dealt one at a time from a stack of cards; a verdict flips the card and reveals the next.
  • One alignment surface - VISION.md is what a reviewer uses; board transcripts stay ephemeral and are never committed next to the vision.

For what the result looks like, see firstmate's VISION.md - produced by exactly this process.

Quick Start

# install (global recommended)
$ npx skills add kunchenguid/vision -g

# in your agent, inside the target repo
/vision
# or: /vision owner/repo

What it needs

  • Read access to the repo and its history: merged PRs via gh or gh-axi when accessible, falling back to default-branch git commit history otherwise.
  • The review board runs on lavish-axi, launched directly through npx -y lavish-axi - nothing to install; a blocker is reported only if the launch itself fails.
  • Any harness: no host-specific agent tools.

How It Works

repo + author
      │
      ▼
┌───────────────────┐
│ learn the pattern │  exemplar visions · anatomy · voice
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ existing vision?  │  yes → delta mode; migrate any answers file
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ mine evidence     │  repo analysis · merged PRs or commit history · evidence sheet
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ draft             │  identity · principles · non-goals · aligns/resisted tests
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ hypotheticals     │  8-12 fault-line proposals, both sides steelmanned
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ review board      │  card-stack verdicts → fold reasoning into draft → approval
└─────────┬─────────┘
          ▼
  VISION.md

Usage

InvokeExample
Slash/vision (in repo) or /vision owner/repo
Natural language"help me write a VISION.md for this project"

The agent should auto-invoke when asked to write, refine, or stress-test a project vision or contribution-acceptance criteria.

Package layout

skills/vision/
  SKILL.md                   # the complete agent contract, self-contained
  assets/
    review.css               # the house-style review surface, used as-is
    review-template.html     # the board template; agents fill slots, never restyle

Ships as an npx skills package.

Development

# edit the skill
$EDITOR skills/vision/SKILL.md

# smoke-test discovery locally
npx skills add ./ -l

# install from this checkout
npx skills add ./ -g -y

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/vision/SKILL.md7.8 KBupstream ↗
    ---
    name: vision
    description: >
      Draft and stress-test a VISION.md for a repository, then iterate with the
      author on an interactive review board until approved. Use on /vision or when
      asked to create or refine a project vision.
    user-invocable: true
    metadata:
      short-description: "Evidence-mined, stress-tested VISION.md for any repo"
    ---
    
    # /vision
    
    You are running the **vision** skill. Produce a VISION.md the author can
    approve: an acceptance policy for the project's future, grounded in what they
    actually build, and sharpened by hypotheticals they answer on an interactive
    review board.
    
    VISION.md is the only committed alignment surface. A reviewer who has never
    seen the board must be able to accept or resist a change from it alone.
    
    This is not a writing exercise. Follow this file top to bottom.
    
    ## Host requirement
    
    You need read access to the target repository and its real history:
    
    - Prefer merged-PR history via a GitHub-class CLI (gh, gh-axi).
    - If PRs are not accessible, fall back to git commit history on the default
      branch (git log): titles and messages still reveal what the author builds.
    - Only if no real history is readable at all, **stop** and say so. Never
      fabricate the author's values, PR titles, or evidence. A vision built on
      invented evidence is worse than no vision.
    
    The review loop runs on lavish-axi, executed directly through
    `npx -y lavish-axi` - no install requirement. Simply try to launch it, and
    report a blocker only if the launch itself fails.
    
    ## Hard rules
    
    1. **Evidence over vibes.** Every principle in the draft must be traceable to
       concrete evidence: named PRs or commits, files, docs, or reasoning the
       author approved into VISION.md. Generic engineering virtues ("we value
       quality") are banned unless the history demonstrates them specifically.
    2. **Check for an existing VISION.md first.** If one exists on the default
       branch, switch to delta mode: treat it as the approved baseline, propose
       line-level candidate changes from evidence newer than it, and never write a
       competing document.
    3. **The author owns the vision.** You draft, stress-test, and fold in their
       verdicts; you never approve, never soften a hypothetical to please, and
       never fold in a principle they did not state or demonstrate.
    4. **A vision is an acceptance policy.** Write testable accept/resist criteria
       in declarative present tense, with explicit non-goals, so a future reader,
       human or agent, can apply them to a concrete change from VISION.md alone.
    5. **No softball hypotheticals.** Each one must sit on a genuine fault line
       where yes and no are both defensible, with both sides steelmanned. If you
       can predict the author's answer, replace the hypothetical.
    6. **The review loop runs on lavish-axi, from the shipped template.** Draft
       and hypotheticals are presented as one board built from
       `assets/review-template.html` + `assets/review.css`, used as-is: black ink
       on white paper set like literature, full draft always fully visible, one
       hypothetical at a time in a card stack. Fill the template's slots; never
       restyle or restructure it, and never substitute another review surface.
    7. **Iterate in batches, trace every edit.** Each author verdict maps to a
       named edit in a changelog; the author must be able to see exactly how their
       answer changed the text.
    8. **Formatting.** One sentence per line. Plain hyphens, never em dashes. No
       roadmap, no feature list, no marketing voice.
    9. **VISION.md is the single alignment surface.** Fold the author's reasoning
       into the prose wherever it matters, in whatever form reads best. Never copy
       hypotheticals or board transcripts into VISION.md. Never write, keep, or
       point to an answers file in the target repo. Board transcripts may live in
       the tool's scratch area and must never be committed.
    
    ## Pipeline
    
    ### Step 0 - Parse target and author
    
    - Target repo: current working directory by default, or an explicit
      owner/repo.
    - Author: the person whose vision this is; default to the repo owner. Their
      merged work is the evidence base.
    - Ask one short question if the target or author is genuinely ambiguous.
    
    ### Step 1 - Learn the pattern
    
    A VISION.md has a stable anatomy; hold the draft to it:
    
    - Identity opener: "X exists so that ...", who it serves, and "It owns exactly
      one thing: ...".
    - 3-6 principle sections with short declarative headings, each a set of
      testable present-tense commitments and refusals.
    - Explicit non-goals, named concretely ("it is not a CI system, not a ...").
    - A closing pair of tests: "A change aligns when ..." and "A change should be
      resisted when ...", concrete enough to apply to a real PR.
    - Voice: declarative, present tense, zero marketing; length a page or two
      (40-70 lines). Author reasoning belongs in the prose wherever it matters,
      in whatever form reads best; never as a ledger of questions asked.
    
    If the author names exemplar visions, read them; note shape, voice, length.
    
    ### Step 2 - Existing-vision check
    
    - If the default branch has a VISION.md: delta mode (hard rule 2). Diff its
      age against the history and propose only evidence-backed candidate
      additions or edits, each independently acceptable.
    - If not: from-scratch mode.
    - If VISION-ANSWERS.md or any companion answers file exists, run Migration
      before drafting: fold any missing reasoning into VISION.md, delete the
      answers file, and remove pointers to it.
    
    ### Step 3 - Mine the evidence
    
    - Repo analysis: README identity claims, architecture, stated non-goals,
      refusal paths, test discipline.
    - History mining: list the author's merged PRs, aim for 30-100 titles, and
      read 8-15 full bodies spread across the range (for example
      `gh pr list --author <owner> --state merged --limit 100`, or the gh-axi
      equivalent). If PRs are inaccessible, walk default-branch commit history
      instead (`git log --author=<owner>`), reading messages for the same signal.
    - Extract recurring revealed values: what gets built, what gets refused, what
      class of bug gets fixed at the root, what the author writes in intent
      statements.
    - Produce a private evidence sheet: value -> supporting PRs, commits, or
      files. This sheet is the source of truth for every drafted line.
    
    ### Step 4 - Draft
    
    - Follow the step 1 anatomy and the output template below.
    - Every line must map to the evidence sheet. Length target: 40-70 lines.
    - Delta mode instead yields: baseline unchanged + a numbered list of candidate
      line additions/edits, each with its evidence.
    
    ### Step 5 - Design the hypotheticals
    
    - 8-12 concrete change proposals per vision, aimed at the draft's fault
      lines. Draw from this taxonomy:
      - tempting-but-off-mission features the author will plausibly be asked for;
      - principle collisions (simplicity vs capability, safety vs speed,
        generality vs focus, cost vs quality);
      - slippery slopes, where one reasonable step normalizes the next;
      - scope expansions (new users, new content types, new hosts, teams);
      - identity questions the draft leaves open.
    - Format per hypothetical: id, title, the concrete proposal (2-4 sentences),
      the principle it tests (quote the draft), and why the answer is non-obvious
      (steelman both sides).
    - Quality gate: delete and replace any hypothetical whose answer you can
      predict.
    
    ### Step 6 - Review loop (lavish-axi, from the shipped template)
    
    - Copy `assets/review-template.html` and `assets/review.css` into the tool's
      scratch area (not the target repo), then fill only the template's marked
      slots: project name, run note, the full DRAFT markdown, and the CARDS array
      (id, title, proposal, tested principle, both-sides steelman per card).
    - Change nothing else: the template already carries the house structure -
      full draft on the left, one card at a time on the right, the steelman in
      full view, one queued verdict per card - so no boilerplate is rewritten and
      no run is restyled.
    - Launch with `npx -y lavish-axi <board.html>`, report the UR
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/kunchenguid-vision-skills-vision.md

// REPO STATS

348 stars
1 open issues
Last commit: 2mo ago