vs-internal-shared

Files (114)

• SKILL.md
• openai.yaml · agents/
• bounded-collaboration.md · references/
• codex-goal.md · references/
• communication.md · references/
• context-docs.md · references/
• disk-backed-evidence.md · references/
• explanation-surfaces.md · references/
• independent-advisors.md · references/
• inline-preview.md · references/
• mcp-apps-host.md · references/
• octocode-access.md · references/
• output-style.md · references/
• phase-boundaries.md · references/
• preview.md · references/
• recording.md · references/
• rich-artifacts.md · references/
• ste-writing.md · references/
• subagents.md · references/
• verify-map.md · references/
• capture-demo.mjs · scripts/
• check-visual-evidence.mjs · scripts/
• cursor-overlay.mjs · scripts/
• evidence-manifest.mjs · scripts/
• pr-media-gate.mjs · scripts/
• pr-media-pairs.mjs · scripts/
• record-flow.mjs · scripts/
• record-pacing.mjs · scripts/
• reject-verify-map.mjs · scripts/
• video-block.mjs · scripts/
• bounded-collaboration.eval.ts · test/
• bounded-collaboration.static.eval.ts · test/
• demo-evidence.eval.ts · test/
• demo-evidence.static.eval.ts · test/
• disk-backed-evidence.static.eval.ts · test/
• evidence-gated-loop.static.eval.ts · test/
• first-pass-comprehension.static.eval.ts · test/
• auth-check.cjs · test/fixtures/bounded-collaboration/
• external-write.cjs · test/fixtures/bounded-collaboration/
• policy.md · test/fixtures/bounded-collaboration/
• scope-check.cjs · test/fixtures/bounded-collaboration/
• brief.md · test/fixtures/explanation-surface/
• LIVE_DRIVE.md · test/fixtures/verify-map/keyword-slogan-launch/
• README.md · test/fixtures/verify-map/keyword-slogan-launch/
• checkout.txt · test/fixtures/verify-map/keyword-slogan-launch/evidence/
• README.md · test/fixtures/verify-map/keyword-slogan-launch/features/
• checkout.md · test/fixtures/verify-map/keyword-slogan-launch/features/
• search.md · test/fixtures/verify-map/keyword-slogan-launch/features/
• settings.md · test/fixtures/verify-map/keyword-slogan-launch/features/
• LIVE_DRIVE.md · test/fixtures/verify-map/live-driven/
• README.md · test/fixtures/verify-map/live-driven/
• checkout.txt · test/fixtures/verify-map/live-driven/evidence/
• README.md · test/fixtures/verify-map/live-driven/features/
• checkout.md · test/fixtures/verify-map/live-driven/features/
• search.md · test/fixtures/verify-map/live-driven/features/
• settings.md · test/fixtures/verify-map/live-driven/features/
• LIVE_DRIVE.md · test/fixtures/verify-map/missing-launch/
• README.md · test/fixtures/verify-map/missing-launch/
• checkout.txt · test/fixtures/verify-map/missing-launch/evidence/
• README.md · test/fixtures/verify-map/missing-launch/features/
• …and 54 more

SKILL.md (first lines)

# internal-shared — internal conventions for vs skills

This skill is a **reference library**, not an executable workflow. Other `skills` skills link to sections below instead of duplicating the rules.

## Project ID convention

Skills that write session artifacts (pushback reports, specs, RFCs, QA reports,
GitHub research docs, briefs, steals, thread analyses, issue drafts) store them
under `~/.vs/$PROJECT_ID/<kind>/...`.

`$PROJECT_ID` resolves, in order:

1. Git remote slug — `owner-repo` parsed from `remote.origin.url` (handles both SSH `git@github.com:owner/repo.git` and HTTPS `https://github.com/owner/repo` forms, strips `.git`, replaces `/` with `-`).
2. Fallback — `$(basename "$PWD")` when no git remote is configured.

The git-slug form is stable across machines and disambiguates same-named repos under different parents (e.g. `alice/foo` vs `bob/foo`).

### Canonical snippet

```bash
PROJECT_ID=$(git config --get remote.origin.url 2>/dev/null \
  | sed -E 's#\.git$##; s#.*[:/]([^/]+/[^/]+)$#\1#; s#/#-#g')
[ -z "$PROJECT_ID" ] && PROJECT_ID=$(basename "$PWD")
ARTIFACTS_DIR="$HOME/.vs/$PROJECT_ID"
```

Paste this inline — skills must stay self-contained in case they're installed standalone outside the vs repo.

### Examples

| Context | `$PROJECT_ID` |
|---|---|
| `git@github.com:vltansky/vs.git` | `vltansky-vs` |
| `https://github.com/acme/foo` | `acme-foo` |
| No git remote, `pwd = /tmp/scratch` | `scratch` |

## Artifact tree layout

```
~/.vs/$PROJECT_ID/
├── pushback/     # pushback stress-test reports
├── specs/        # shape-it design docs
├── rfcs/         # rfc-research RFCs
├── qa-reports/   # qa QA reports + screenshots
├── vs-octocode/  # Octocode prior-art docs and landscape maps
├── briefs/       # brief outputs
├── reviews/      # code-review diffs, scans, and evidence
├── verification/ # verification result summaries
├── perf/         # performance baselines and evaluator checkpoints
├── prototypes/   # prototype questions, decisions, and evidence
├── videos/       # explain-video scenes, narration, and mp4 output
├── improve/      # improvement backlog plans and indexes
├── sessions/     # workflow session handoffs
├── thread-analysis/ # cross-session thread comparison reports
├── issues/       # to-issues drafts / index
└── steals/       # steal reports
```

## Communication contract

Use [`references/communication.md`](./references/communication.md) in every
workflow skill. It defines the chat budget, the visual progress checkpoint
(Alignment. Shaping. Your input needed. Handoff.), phase-boundary emissions, when a run owes the
user an artifact, how to open one, and the install-freshness rule that makes
skill changes take effect at all.

## Output style

Use [`references/output-style.md`](./references/output-style.md) in every
user-facing skill — it applies to chat messages, not just workflow handoffs. It
defines the answer-first handoff and the optional `Your action`, `Verified`,
and `Still unverified` sections, plus the procedural sentence constraints that
apply to any step the user executes. Communication decides what reaches chat;
this decides how it is arranged once there.

## Explanation surfaces

Use [`references/explanation-surfaces.md`](./references/explanation-surfaces.md)
before writing a human-facing explanation. It decides whether the result stays
in short chat or uses the two-layer chat TLDR plus visual HTMDX contract, how to
choose a trustworthy visual, and when one useful question belongs.

## STE writing

Use [`references/ste-writing.md`](./references/ste-writing.md) when a skill
writes procedural or beginner-facing prose: steps, runbooks, PR bodies, and
from-zero explainers. `vs-write` owns the rules and
`skills/vs-write/scripts/check-ste.mjs` enforces them; other skills link here
and run the checker.

## Agent-owned previews

Use [`references/preview.md`](./references/preview.md) when a skill needs a
running surface to capture evidence. It defines the resolution order, how to
start and record an ephemeral preview, who stops it, and the one deliberate
exception where `vs-ship-it` leaves one running for the user.

## Rich human-facing artifacts

Use [`references/rich-artifacts.md`](./references/rich-artifacts.md) when a
skill may produce an HTMDX report or dashboard. It defines the selection gate,
single-file source contract, pinned runtime, and sensitive-data fallback.

## Disk-backed evidence

Use [`references/disk-backed-evidence.md`](./references/disk-backed-evidence.md)
when screenshots, DOM snapshots, transcripts, diffs, logs, recordings, or other
large evidence could consume model context. It defines the content-addressed
manifest, bounded summaries, and targeted retrieval contract.

## Verify map

Use [`references/verify-map.md`](./references/verify-map.md) when a consumer
repo needs a scripted launch, doctor, and drive path. It defines the cold-read
contract, the interview axes, the live-drive gate, and the project-local
`.vs/verify-map/` output. Generate a map, not a skill.

## What does NOT go here

From vltansky/vs, MIT.

More from vltansky/vs