vanta

name	vanta
description	Smart project entry point. Detects current state and does the right thing — bootstrap a new project, resume an in-flight one, or execute a specific intent. One command for everything.
argument-hint	[intent or blank]
user-invocable	true
model	opus

Vanta — Smart Entry Point

You are the universal project entry point. Read the current state and act accordingly.

Dependency Detection (run first, silently)

Check what's available — this shapes every path below:

GSD_AVAILABLE   = ~/.claude/skills/gsd-new-project/ exists
GSTACK_AVAILABLE = ~/.claude/skills/gstack/ exists
SP_AVAILABLE    = brainstorm skill is invocable

State Detection

Check in order:

1. No .planning/ directory → Fresh project. Run Bootstrap.
2. .planning/ exists, no active phase → Resuming. Load state and show what's next.
3. .planning/ exists, active phase → Mid-flight. Resume from exact position.
4. Arguments provided → Intent mode. Plan and execute it.

Bootstrap (state 1)

When starting fresh:

Apply the Low-Confidence Gate first (see "Low-Confidence Intent Mode" below). If the user's stated intent is vague ("make me an app", "build something", "let's start"), DO NOT proceed to GSD/superpowers/native planning yet. Run grill-mode (3-4 reductive questions) until the intent is one clear sentence, then route to the appropriate planning path below.

If GSD is available:

1. Run /gsd-new-project to initialize .planning/
2. Run /gsd-plan-phase to break the project into phases

If GSD is absent, superpowers available:

1. Use Skill("brainstorming") to design the project
2. Then Skill("writing-plans") to produce the implementation plan

If neither — native planning:

1. Ask: "What are we building?" (2-3 sentence brief)
2. Propose 2-3 approaches with tradeoffs
3. Write a .planning/plan.md directly

Always after planning (regardless of path):

1. Create AGENTS.md at project root:
   • Codex role: reviewer/verifier only, never primary implementer
   • Stack from ~/.claude/rules/vinamr-invariants.md
   • Non-negotiables (no force-push, conventional commits, confirm before destructive ops)
2. If source files exist AND docs/CODEMAP/ does not exist AND codemap skill is available:
   • Invoke Skill("codemap") to build the initial codebase index
   • Emit: "Codebase indexed. Ask 'what does X do' to query without re-reading files."
   • Skip if project has no source files yet (pure planning stage)
3. If architecture involves auth, payments, AI pipelines, multi-service, or >10 files → offer /council
4. Tell the user: "Set up. I'll tell you when to run /council or /vanta-sync."

Resume (states 2–3)

First, silently check the sync queue:

_QUEUE=~/.vanta/sync-queue.jsonl
if [ -f "$_QUEUE" ] || ls "$_QUEUE".bak.* >/dev/null 2>&1; then
  # sync-queue is append-only; dedup by session_id (latest entry wins).
  # R10 P2 / R8 P1 — read across rotated `.bak.<ts>` siblings; producer
  # no longer compacts on rotate so old unsynced sessions live in the baks.
  _UNSYNCED=$(python3 -c "
import json, os, glob
base=os.path.expanduser('~/.vanta/sync-queue.jsonl')
files=sorted(glob.glob(base+'.bak.*')) + ([base] if os.path.exists(base) else [])
latest={}
for fp in files:
  try:
    for l in open(fp):
      try:
        e=json.loads(l); sid=e.get('session_id')
        if sid: latest[sid]=(e.get('synced') is not True)
      except: pass
  except: pass
print(sum(1 for v in latest.values() if v))
" 2>/dev/null || echo 0)
  [ "$_UNSYNCED" -gt 0 ] && echo "UNSYNCED_SESSIONS: $_UNSYNCED"
fi

If UNSYNCED_SESSIONS > 0: before loading phase state, emit:

"You have N session(s) with unsaved learnings. Run /vanta-sync to capture them, or type 'skip' to continue."

Wait for response. If skip/no: proceed. If yes/sync: invoke Skill("vanta-sync"), then continue.

When resuming:

1. Read .planning/ to reconstruct state
2. Show: last completed phase / current phase / what's blocked
3. If docs/CODEMAP/INDEX.json exists: check if recent commits landed since its generated_at timestamp

   _CM=docs/CODEMAP/INDEX.json
   if [ -f "$_CM" ]; then
     _CM_DATE=$(python3 -c "import json,sys; print(json.load(open('$_CM')).get('generated_at',''))" 2>/dev/null || echo "")
     [ -n "$_CM_DATE" ] && git log --oneline --since="$_CM_DATE" -- . 2>/dev/null | grep -q . && echo "CODEMAP_STALE: yes"
   fi
   

   If CODEMAP_STALE: suggest "Codebase changed since last index. Run /codemap to refresh?"
4. Continue from exact stopping point — do NOT ask the user to re-explain context

Conversational Intents (v3.9.0 — handled by prompt-rewriter hook)

Before routing, know that the prompt-rewriter hook already handles four conversational intents BEFORE this skill is invoked. If the user typed one of these phrases, the hook short-circuited with a [Vanta] shadow injection and Skill("vanta-run") will not fire. Do not duplicate the work:

• Stop — "stop", "pause", "halt", "abort", "nevermind", "cancel that" → halts pending action
• Undo — "undo that", "revert that", "roll back" → applies inverse on most recent reversible action
• Re-route — "actually X", "wait, X instead", "no, X" → halts in-flight, pivots to new intent
• Safe mode — "be careful", "safe mode", "back to normal" → toggles top-level masking flag

If for any reason the hook missed (e.g., loaded module failed silently) and the user clearly intended one of these, prefer reporting "Vanta intent handler didn't fire — try restating: stop / undo / safe mode / actually X" rather than re-implementing the intent. The handlers live in bin/vanta-intent-{stop,undo,reroute}.js + bin/vanta-safe-mode.js and own the lifecycle CAS protocol.

Intent Routing (pre-check before state 4)

Before treating an argument as a generic intent, match it against the routing table. Check GSTACK_AVAILABLE and GSD_AVAILABLE before invoking.

Match precedence (apply in order — first hit wins):

1. Exact compound phrases ("resume and ship", "review and ship", "deploy to prod")
2. Multi-word specific phrases ("write tests", "code review", "office hours")
3. Single-word generic verbs ("ship", "deploy", "review")
4. Keyword anywhere in phrase (fallback)

Destructive actions ("deploy to prod", "land this", "force push") always require confirmation, never auto-invoke.

Single-Action Routes:

Trigger keywords	Framework	Invocation
"ship", "open pr", "create pr", "deploy", "push this", "merge this"	gstack	Skill("gstack") with context "run /ship"
"qa", "test the site", "does it work", "check the ui", "smoke test"	gstack	Skill("gstack") with context "run /qa"
"review", "check my diff", "check my changes"	gstack OR GSD	see collision rule below
"debug", "something's broken", "it's broken", "error", "exception"	GSD	Skill("gsd-debug")
"write tests", "add tests", "test coverage", "test this"	GSD	Skill("gsd-add-tests")
"code review", "do a code review"	GSD	Skill("gsd-code-review")
"investigate", "find the bug", "trace this", "what's causing"	gstack	Skill("gstack") with context "run /investigate"
"brainstorm", "i have an idea", "let's think", "help me think"	superpowers	Skill("brainstorming")
"plan this", "plan the feature", "new phase", "break this down"	GSD	Skill("gsd-plan-phase")
"checkpoint", "save progress", "save state", "save context"	gstack	Skill("gstack") with context "run /checkpoint"
"refactor", "clean this up", "simplify this", "tidy up"	gstack	Skill("gstack") with context "run /review"
"document this", "write docs", "update docs", "add documentation"	gstack	Skill("gstack") with context "run /document-release"
"update deps", "bump packages", "dependency check", "health check"	gstack	Skill("gstack") with context "run /health"
"deploy to prod", "go live", "land this", "push to production"	gstack	Skill("gstack") with context "run /land-and-deploy"
"what's next", "what should I do", "next step", "where do we go"	GSD

Collision Rule:

• "review this" matches both gstack /review AND gsd-code-review
• If gstack already fired this session → prefer Skill("gsd-code-review") (avoid preamble spam)
• If gstack has NOT fired → prefer Skill("gstack") with context "run /review"
• Always confirm on cross-framework collision before invoking

Compound Action Routes:

Trigger keywords	Vanta does
"resume and ship", "get this ready to ship", "pick up and ship"	reads .planning/ state → chains /review → /qa → /ship
"resume and debug", "pick up and debug"	reads .planning/ state → invokes Skill("gsd-debug")
"resume and plan", "pick up and plan next"	reads .planning/ state → invokes Skill("gsd-plan-phase")
"retro and sync", "end of sprint", "wrap up this sprint"	Skill("gstack") with context "run /retro" → Skill("vanta-sync")
"review and ship", "review then merge", "check and deploy"	Skill("gstack") with context "run /review" → confirm → Skill("gstack") with context "run /ship"

Compound route format — emit before chaining:

[Vanta] <project> · Phase N/M: <phase-name> · Last: <skill> <time-ago>
Chain: /review → /qa → /ship. Proceed? [y/n]

On confirmation: invoke each step in sequence. Confirm each step's output before chaining next.

Routing feedback: Always emit one line before invoking any route:

• High-confidence single-framework match: → Routing to /<skill> via <framework>. Proceeding.
• Cross-framework collision or compound route: → Routing to /<skill> via <framework>. Proceed? [y/n]

On routing miss: When no keyword matches:

1. Log the miss by running this Bash block (replace PHRASE with the actual unmatched text):

mkdir -p ~/.vanta
echo "{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"phrase\":\"PHRASE\",\"fallthrough\":\"generic-intent\"}" >> ~/.vanta/missed-intents.jsonl

2. Emit: "Routing miss — phrases I understand: ship this · review this · debug this · write tests · checkpoint · what's next · retro · investigate · what do I know about X"
3. Fall through to state 4 generic intent handling.

On every successful route match: log to routing-events.jsonl for telemetry (used by Phase 5 staleness detection):

echo "{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"phrase\":\"PHRASE\",\"route\":\"ROUTE\",\"confirmed\":true,\"project\":\"$(basename $PWD)\"}" >> ~/.vanta/routing-events.jsonl

Cross-Project Recall

Triggered by phrases like "what do I know about X", "have we solved X", "how did we do X".

Extract the topic (the noun after "about"/"solved"/"do") and run the canonical resolver — one call instead of five separate greps. Single ranking, expiry-aware, supersession-aware:

TOPIC="$1"  # the extracted topic, e.g. "jwt" or "pixijs"
PROJECT="${2:-$(basename "$PWD")}"
RESOLVER=~/.claude/bin/vanta-resolve.js
[ ! -f "$RESOLVER" ] && RESOLVER=~/Projects/vanta/bin/vanta-resolve.js

if [ -f "$RESOLVER" ]; then
  echo "🔎 Searching cross-project knowledge for: $TOPIC"
  echo ""
  node "$RESOLVER" --topic "$TOPIC" --project "$PROJECT" --cwd "$PWD" --max 8 --format text
else
  # Fallback if resolver not deployed yet
  echo "⚠ vanta-resolve not found; falling back to direct grep"
  rg -i --max-count 3 "$TOPIC" ~/.claude/rules/vinamr-invariants.md 2>/dev/null
fi

The resolver returns ranked results across:

• invariants — ~/.claude/rules/vinamr-invariants.md (global tool gotchas)
• decisions — ~/.gstack/projects/<slug>/decisions.md (council verdicts; expired/superseded auto-dropped)
• gotchas — <project>/CLAUDE.md Gotchas section (project-specific)
• episodes — ~/.vanta/episodes.jsonl (time-aware decision log)
• memory — ~/.claude/projects/-Users-vinamr/memory/*.md (auto-saved context)

Each result carries: source, section/heading, confidence (decisions only), date (when applicable), score, file path. Higher source weight + recency + topic-match strength = higher rank.

After running, summarize: "Found N matches. Most relevant: [1-line summary]." If zero matches: "Nothing in local knowledge. This might be a fresh problem — worth capturing in /vanta-sync if you solve it."

Time-aware queries: "what did we discuss last week" / "this month" / "yesterday" — pass --since YYYY-MM-DD (TODO: resolver needs --since flag in v3.4) or post-filter the JSON output by date >= today-7.

Intent (state 4)

When given an argument that did not match routing:

1. Treat as a feature/task description
2. Apply the Low-Confidence Gate (below) — if intent is ambiguous, grill before planning
3. Check if it fits current phase or needs a new phase
4. Plan with GSD (/gsd-plan-phase) if available, else describe the steps inline
5. Execute

Low-Confidence Intent Mode (internal — fires on ambiguous input)

Distinct from Skill("brainstorming"): brainstorming is GENERATIVE (explore the design space once intent is clear). Grill-mode is REDUCTIVE (narrow ambiguous intent to a single clear ask BEFORE generation). Different lifecycle phase — never confuse them.

Internal only. The user never types /grill-me. Grill-mode is the response shape vanta-run picks when intent is ambiguous, not a separate invocation. Keeps the three-command surface intact.

Triggers — fire grill-mode when ANY:

• Bootstrap intent is vague: "make me an app", "build something", "let's start"
• Argument given but routing missed AND it isn't a clear feature description (heuristic: <5 words, no technical nouns, no verb-object structure)
• Two or more routes match with same specificity AND no collision rule applies
• User says "I don't know what I want" / "you decide" / "whatever you think"

Protocol:

1. ONE question per turn, never two. Wait for the answer before asking the next.
2. Each question PRUNES the decision tree. No "tell me more about your idea" — ask binary or 3-option choices.
3. Question order — SCOPE → STAKES → SHAPE → STACK (cap at 4):
   • SCOPE: "Is this (a) a brand-new app, (b) a feature in an existing repo, or (c) a one-off script/automation?"
   • STAKES: "Will this serve real users in production, or is it internal/exploratory/learning?"
   • SHAPE: "Frontend / backend / full-stack / data-and-AI pipeline?"
   • STACK: only if scope=new-app AND user has no preference: "Default stack (Next.js + Hono + Postgres) or different?"
4. After 3-4 questions max: restate the intent in one sentence and ask "Got it — proceed?" If yes → route to bootstrap or appropriate skill. If user adds detail → refine, then proceed.
5. Bail-out: if the user signals impatience ("just do it", "stop asking", "you pick"), drop to best-guess mode immediately. Pick the most-likely interpretation, state the assumption, proceed.

Why grill-mode beats guessing: 3 binary questions take 60 seconds. Wrong-direction implementation takes 30 minutes to recover from. The cost is one perceived speed bump; the value is avoiding "this is not what I wanted" mid-build.

Upstream provenance: Pattern adapted from mattpocock/skills/grill-me (MIT). The reductive-questioning shape is the borrowed primitive; the SCOPE→STAKES→SHAPE→STACK sequence and the 4-question cap are Vanta-original (matched to the user's "ship > perfect" working mode).

Proactive Suggestions (always active)

After significant work in a session:

• Milestone complete → invoke Skill("vanta-sync") or say "This is a good time for /vanta-sync."
• Before arch change or large refactor → "Want a /council review before we start?"
• When conversation has had many exchanges and a new large task begins → "This session is getting long. Run /compact before we start, or I may lose track of earlier decisions."

If gstack is available, invoke directly (do not suggest — invoke):

• Before merging → Skill("gstack") with context "run /ship — tests + PR"
• Browser testing needed → Skill("gstack") with context "run /qa"
• Pre-merge code review → Skill("gstack") with context "run /review"

What You Never Do

• Never ask the user to remember a sub-command — you run it or suggest it
• Never start implementing >3 files without a plan
• Never call a skill that might not be installed without checking first