check

name	check
description	Run full production readiness assessment. Use when the user wants to evaluate if their app is ready for real users — checks security, performance, accessibility, testing, monitoring, CI/CD, discoverability, analytics, reliability, legal, and platform concerns.
user-invocable	true
args	[{"name":"focus","description":"Optional domain to focus on (security, performance, accessibility, testing, monitoring, ci-cd, discoverability, analytics, platform, reliability, legal)","required":false}]
hooks	{"PreToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"command","command":"node \"${SKILL_DIR}/scripts/scan-secrets.js\"","timeout":10}]}]}

Vibe Check

Run a complete production readiness assessment and write all results to the .vibe-check/ directory. This is the primary command for evaluating a project's production readiness.

Reference Files

Read these as needed — not all at once upfront:

• reference/domains.md — Criteria for what "good" looks like in each domain
• reference/scoring.md — Score calculation, bands, critical gate rule
• reference/agent-classification.md — How to classify items as agent-fixable
• agents/mapper.md — Spawn instructions for codebase mapper
• agents/assessor.md — Spawn instructions for domain assessors
• templates/ — Output templates (summary, report, checklist-item, action-plan, etc.)

Architecture

You are the orchestrator. You delegate heavy work to specialized agents and stay lean.

check (orchestrator)
    |
    +-- Phase 1: Setup
    |   +-- Create .vibe-check/ directory
    |
    +-- Phase 2: User Input
    |   +-- Ask 4 context questions (what, who, data, stakes)
    |
    +-- Phase 3: Codebase Mapping
    |   +-- Spawn: mapper agent
    |       +-- Writes: .vibe-check/analysis/*.md
    |       +-- Returns: confirmation only
    |
    +-- Phase 4: Domain Assessment
    |   +-- Spawn: assessor agents (can be parallel)
    |       +-- security assessor
    |       +-- performance assessor
    |       +-- accessibility assessor
    |       +-- testing assessor
    |       +-- monitoring assessor
    |       +-- ci-cd assessor
    |       +-- discoverability assessor
    |       +-- analytics assessor
    |       +-- platform assessor (informational-only)
    |       +-- reliability assessor
    |       +-- legal assessor
    |       +-- ai-security assessor (conditional: only if AI patterns detected)
    |       +-- Each writes: .vibe-check/checklist/item-*.md
    |       +-- Each returns: score summary only
    |
    +-- Phase 5: Aggregate & Write
    |   +-- You write: summary.md, report.md, action-plan.md, index.md, metadata.json, README.md
    |
    +-- Phase 6: Terminal Output
    |   +-- Show score and next steps
    |
    +-- Phase 7: Offer Discussion
        +-- Ask user what they want to do next

Why this architecture:

• Mapper explores entire codebase (heavy context) — writes to files, returns nothing
• Assessors evaluate domains (heavy judgment) — write items, return scores
• Orchestrator stays under 30% context — can write final files clearly

Process

Phase 1: Setup

Create output directories. If .vibe-check/ already exists from a previous run, clean it out first to avoid stale data mixing with fresh results:

# Remove previous assessment if it exists
if [ -d ".vibe-check" ]; then
  rm -rf .vibe-check/analysis .vibe-check/checklist
  rm -f .vibe-check/metadata.json .vibe-check/summary.md .vibe-check/report.md .vibe-check/action-plan.md .vibe-check/README.md
fi

# Create all required directories
mkdir -p .vibe-check/checklist .vibe-check/analysis

This step is required before any agents run or any files are written. If directories don't exist, Write tool calls will fail.

Phase 2: User Input

Ask only what you need. Use concrete options. Questions should be answerable by someone who can't read code.

Question 1: What is this?

header: "Project"
question: "In a sentence, what does this thing do?"
options:
- "Let me describe it" (free text)

This is an open question. Let them describe it in their own words. You'll use this to contextualize findings.

Question 2: Who's it for?

header: "Users"
question: "Who will use this?"
options:
- "Just me / internal tool"
- "Specific people I know (clients, team)"
- "Anyone on the internet"
- "Let me explain"

This determines exposure level:

• Just me -> relax on legal, auth can be simpler
• Specific people -> moderate security, some legal
• Public -> strict on everything

Question 3: What data are you handling?

header: "Data"
question: "What are users giving you?"
options:
- "Nothing sensitive (content, preferences)"
- "Account info (email, password)"
- "Money (payments, billing)"
- "Personal details (health, financial, identity)"

This determines compliance needs without asking about compliance:

• Nothing sensitive -> no special requirements
• Account info -> standard security practices
• Money -> PCI considerations, stricter security
• Personal details -> likely GDPR/HIPAA territory, strict everything

Question 4: What's at stake?

header: "Stakes"
question: "What happens if this breaks for a day?"
options:
- "Nothing, it's a side project"
- "Annoying, but no real damage"
- "I lose money or trust"
- "Serious consequences (legal, safety)"

This determines how strict to be overall:

• Side project -> focus on quick wins only
• Annoying -> standard rigor
• Lose money/trust -> thorough assessment
• Serious -> enterprise-grade expectations

Defaults:

If user skips or seems unsure, use sensible defaults:

• Users: Assume public
• Data: Assume account info
• Stakes: Assume "lose money or trust"

Err toward caution when defaulting.

Store context:

Save their answers for assessors. This goes in metadata.json under context:

{
  "context": {
    "description": "{their description}",
    "audience": "personal|known|public",
    "dataSensitivity": "none|accounts|payments|sensitive",
    "stakes": "none|low|medium|high"
  }
}

Pass this context to assessors so they can calibrate scoring.

Phase 3: Codebase Mapping

If subagent spawning is available, spawn a mapper agent:

Task: Map codebase for readiness assessment

Read agents/mapper.md for your instructions.

Explore this codebase and write analysis files to .vibe-check/analysis/

Return confirmation only when complete.

If subagent spawning is NOT available, perform the mapping yourself:

1. Read agents/mapper.md for the exploration process
2. Follow the compact mode or standard mode steps depending on codebase size
3. Write all 17 analysis files to .vibe-check/analysis/
4. Continue to Phase 4

Wait for confirmation. The mapper writes 17 analysis files and returns:

• Mode (Compact or Standard)
• AI patterns detected (Yes/No)
• Capabilities detected (Database, Auth, Server/Backend, Analytics SDK, AI patterns, UI/Frontend, CI Pipeline, Test Runner)
• Coverage notes (what received lighter review or was skipped — keep these for the report's Assumptions section)

Do not read the analysis files. The assessors will read them. Use the capabilities summary to decide which assessors to skip (Phase 4).

Phase 4: Domain Assessment

Spawn assessor agents for each domain group. These can run in parallel.

Conditional domain skipping based on mapper capabilities + user context:

Use the mapper's capabilities summary to skip entire assessor domains when the domain cannot apply. This extends the existing AI Security pattern:

Condition	Skip
AI patterns: No	AI Security domain
stakes=none + Analytics SDK: No	Analytics domain
audience=personal + data=none	Legal domain
No UI/Frontend detected	Accessibility domain -> mark all N/A
No UI/Frontend + No Server/Backend	Performance domain -> mark all N/A

When a domain is skipped:

• Do NOT spawn the assessor
• Record all items as N/A in metadata
• Set effectiveMax: 0 for that category

Individual item-level N/A detection (e.g., no database -> Backups N/A) is handled within assessors using the N/A rules in their instructions. Pass mapper capabilities in the context block so assessors can reference them.

Security Assessor:

If subagent spawning is available:

Task: Assess security domain

Read agents/assessor.md for your instructions.
Your domain assignment is: security

Project context (calibrate your assessment accordingly):
- Description: {description from user}
- Audience: {personal|known|public}
- Data sensitivity: {none|accounts|payments|sensitive}
- Stakes: {none|low|medium|high}

Mapper capabilities:
- Database: {Yes|No}
- Auth: {Yes|No}
- Server/Backend: {Yes|No}
- Analytics SDK: {Yes|No}
- AI patterns: {Yes|No}
- UI/Frontend: {Yes|No}
- CI Pipeline: {Yes|No}
- Test Runner: {Yes|No}

Load these analysis files:
- .vibe-check/analysis/secrets.md
- .vibe-check/analysis/auth.md
- .vibe-check/analysis/dependencies.md

Read reference/domains.md for evaluation criteria.
Read reference/agent-classification.md for agent-doable classification.

Evaluate: Secrets Management, Authentication, Input Validation, Dependency Security, HTTPS, Security Headers, CORS Configuration, Rate Limiting, CSRF Protection

Write failing/unknown items to .vibe-check/checklist/
Return score summary only.

If subagent spawning is NOT available, perform the assessment yourself:

1. Read agents/assessor.md for the evaluation process
2. Read the relevant analysis files and reference files
3. Evaluate items and write checklist files to .vibe-check/checklist/
4. Track scores for aggregation in Phase 5

Pass context AND mapper capabilities to all assessors. They use context to calibrate and capabilities to detect N/A items:

• Personal tool with no sensitive data -> relax on legal, simpler auth is fine
• Public app handling payments -> strict on everything
• Side project -> focus on critical issues only

Discoverability Assessor:

Task: Assess discoverability domain
Domain assignment: discoverability
Analysis files: discoverability.md, stack.md
Evaluate: Meta Tags, OpenGraph Tags, Twitter Cards, Sitemap, robots.txt, Semantic HTML

Analytics Assessor:

Task: Assess analytics domain
Domain assignment: analytics
Analysis files: analytics.md
Evaluate: Visitor Tracking, Conversion Tracking

Platform Assessor:

Task: Assess platform domain
Domain assignment: platform
Note: This domain is informational-only. Assess items but report earned=0, max=0.
Analysis files: stack.md, infrastructure.md, integrations.md, platform.md
Evaluate: Hosting Compatibility, Complexity Check, Cost Signals, Managed Services

Reliability Assessor:

Task: Assess reliability domain
Domain assignment: reliability
Analysis files: error-handling.md, data.md, integrations.md
Evaluate: Backups, Error Handling, Database Connections

Legal Assessor:

Task: Assess legal domain
Domain assignment: legal
Analysis files: legal.md, data.md
Evaluate: Privacy Policy, Terms of Service, Cookie Consent, User Data Deletion

Performance Assessor:

Task: Assess performance domain
Domain assignment: performance
Analysis files: performance.md, stack.md, data.md
Evaluate: Image Optimization, Code Splitting, Data Fetching & Caching, Font Optimization, DB Query Performance

Accessibility Assessor:

Task: Assess accessibility domain
Domain assignment: accessibility
Analysis files: accessibility.md, stack.md
Evaluate: Image Alt Text, Form Label Association, Keyboard Navigation, ARIA & Semantic HTML, Motion Accessibility

Testing Assessor:

Task: Assess testing domain
Domain assignment: testing
Analysis files: testing.md, stack.md
Evaluate: Test Runner Configured, Test Files Exist, E2E Testing Setup, Tests Run in CI

Monitoring Assessor:

Task: Assess monitoring domain
Domain assignment: monitoring
Analysis files: infrastructure.md, error-handling.md, analytics.md
Evaluate: Error Tracking, Structured Logging, Health Check Endpoint, APM

CI/CD Assessor:

Task: Assess ci-cd domain
Domain assignment: ci-cd
Analysis files: ci-cd.md, infrastructure.md, data.md
Evaluate: CI Pipeline Exists, Build Verification, DB Migration Strategy, Environment Separation

AI Security Assessor (Conditional):

Only spawn this assessor if the mapper indicated AI patterns were detected. Check the mapper's confirmation message for "AI patterns detected: Yes".

Task: Assess AI security domain

Read agents/assessor.md for your instructions.
Your domain assignment is: ai-security

Project context (calibrate your assessment accordingly):
- Description: {description from user}
- Audience: {personal|known|public}
- Data sensitivity: {none|accounts|payments|sensitive}
- Stakes: {none|low|medium|high}

Mapper capabilities:
- Database: {Yes|No}
- Auth: {Yes|No}
- Server/Backend: {Yes|No}
- Analytics SDK: {Yes|No}
- AI patterns: {Yes|No}
- UI/Frontend: {Yes|No}
- CI Pipeline: {Yes|No}
- Test Runner: {Yes|No}

Load these analysis files:
- .vibe-check/analysis/ai-security.md
- .vibe-check/analysis/auth.md
- .vibe-check/analysis/integrations.md

Read reference/domains.md for evaluation criteria.
Read reference/agent-classification.md for agent-doable classification.

Evaluate: Prompt Injection Prevention, Function Calling Safety, WebSocket Origin Validation, Plugin Ecosystem Security, Context Isolation

Write failing/unknown items to .vibe-check/checklist/
Return score summary only.

If the mapper indicated "AI patterns detected: No", skip this assessor entirely and note in metadata that AI Security domain was not applicable.

Collect score summaries from each assessor.

Phase 5: Aggregate & Write

You now have:

• Score contributions from each assessor (including N/A counts)
• Strengths (Pass items with evidence) from each assessor
• Open questions (verification questions for Unknown items) from each assessor
• List of checklist item files written
• Mapper capabilities and coverage notes

Calculate total score and write final files. Read reference/scoring.md for the scoring methodology.

Root-cause themes

Before writing summary.md and report.md, look across all assessor results for shared causes. Findings often trace back to 2–4 root causes — e.g., "no CI pipeline" explains tests-not-in-CI, no build verification, and no environment separation across three domains; "no observability" explains error tracking, logging, and APM fails. Name those themes in the executive summary so the user sees a few fixable problems instead of twenty disconnected items. Only name themes that genuinely explain multiple findings — if the findings are unrelated, say so rather than forcing a pattern.

What not to fix

Context calibration shouldn't be silent. Using the user's audience/data/stakes answers, identify failing items that are honestly not worth their time right now (e.g., Low-priority polish on a side project, E2E testing before there are users) and list them in action-plan.md with a one-line reason each. Never put Critical items here. This is a recommendation to defer, not a status change — the items stay in the checklist and score.

metadata.json

{
  "project": "{from package.json name or directory}",
  "analysisDate": "{YYYY-MM-DD}",
  "score": "{normalizedScore}",
  "adjustedEarned": "{adjustedEarned}",
  "adjustedMax": "{adjustedMax}",
  "scoringVersion": "v2",
  "band": "{Early Stage|Needs Work|Launch Ready|Production Ready}",
  "criticalGate": "{true|false}",
  "criticalItems": ["{item-NNN title}", "..."],
  "aiDetected": "{true|false}",
  "mapper": {
    "mode": "{Compact|Standard}"
  },
  "context": {
    "description": "{what they said it does}",
    "audience": "{personal|known|public}",
    "dataSensitivity": "{none|accounts|payments|sensitive}",
    "stakes": "{none|low|medium|high}"
  },
  "categories": {
    "security": {"earned": "N", "max": 15, "effectiveMax": "N", "na": "N", "applicable": true},
    "performance": {"earned": "N", "max": 12, "effectiveMax": "N", "na": "N", "applicable": true},
    "accessibility": {"earned": "N", "max": 12, "effectiveMax": "N", "na": "N", "applicable": true},
    "testing": {"earned": "N", "max": 10, "effectiveMax": "N", "na": "N", "applicable": true},
    "monitoring": {"earned": "N", "max": 10, "effectiveMax": "N", "na": "N", "applicable": true},
    "ci-cd": {"earned": "N", "max": 10, "effectiveMax": "N", "na": "N", "applicable": true},
    "discoverability": {"earned": "N", "max": 10, "effectiveMax": "N", "na": "N", "applicable": true},
    "analytics": {"earned": "N", "max": 8, "effectiveMax": "N", "na": "N", "applicable": "true|false"},
    "platform": {"earned": 0, "max": 0, "effectiveMax": 0, "na": "N", "applicable": true, "informational": true},
    "reliability": {"earned": "N", "max": 8, "effectiveMax": "N", "na": "N", "applicable": true},
    "legal": {"earned": "N", "max": 5, "effectiveMax": "N", "na": "N", "applicable": "true|false"},
    "ai-security": {"earned": "N", "max": 12, "effectiveMax": "N", "na": "N", "applicable": "true|false"}
  },
  "checklist": {
    "pass": "N",
    "fail": "N",
    "unknown": "N",
    "na": "N"
  },
  "items": [
    {"id": "item-001", "slug": "secrets-management", "status": "Fail", "na": false},
    {"id": "item-002", "slug": "authentication", "status": "N/A", "na": true}
  ]
}

Notes:

• When a category has applicable: false, it is entirely excluded from scoring (effectiveMax = 0)
• na count per category shows how many items were marked N/A
• criticalGate is true when Critical fails cap the band at "Needs Work"
• criticalItems lists the titles of Critical-priority Fail items (empty array if none)
• resolvedUnknowns (optional array) is added by the resolve-unknowns flow in Phase 7 — see that section for the shape

summary.md

Use templates/summary.md as reference. Include:

• Score and band
• What's working (top strengths from assessor summaries — pick the most meaningful, not all)
• Top 3 risks
• Quick wins (agent-doable, high-impact)
• Open questions (only if Unknown items exist)
• Next steps

report.md

Use templates/report.md as reference. Include:

• Executive summary (lead with root-cause themes)
• What's working (strengths grouped by domain, with evidence)
• Score breakdown by category
• Top risks with severity
• Open questions (verification questions for Unknown items)
• Assessment profile (deployment, compliance)
• Assumptions and coverage notes (from the mapper)
• Checklist overview table

action-plan.md

Use templates/action-plan.md as reference. Include:

• Short-term (critical/high priority fails)
• Mid-term (medium priority)
• Long-term (low priority, nice-to-haves)
• Not worth fixing right now (deferred items with reasons, per "What not to fix" above)

checklist/index.md

Use templates/checklist-index.md as reference. Include:

• Summary counts
• Items grouped by priority
• Items grouped by domain
• Agent-doable items list

README.md

Use templates/vibe-check-readme.md as reference.

Phase 6: Terminal Output

Display summary with the score banner:

+----------------------------------------------+
|                                              |
|   VIBE CHECK COMPLETE                        |
|                                              |
|   Score: {score}/100                         |
|   {progress_bar}  {band}                     |
|                                              |
+----------------------------------------------+

{If criticalGate is true:}
+-- WARNING -----------------------------------+
|                                             |
|  ! Critical issues prevent Production Ready / Launch Ready status: |
|  * {critical item title}                    |
|  * {critical item title}                    |
|                                             |
+---------------------------------------------+

Created .vibe-check/ with {N} checklist items:
  Pass     {pass}
  Fail     {fail}
  Unknown  {unknown}
  N/A      {na}

{If agent-doable items exist:}
{N} items are agent-doable. Top priorities:
  {title} -- {one-line description}
  {title} -- {one-line description}
  {title} -- {one-line description}

{If Unknown items exist:}
{N} items couldn't be verified from code alone (marked Unknown, small score
penalty). Answering a few quick questions can firm up your score.

+-- NEXT --------------------------------------+
|                                             |
|  * Review: .vibe-check/summary.md           |
|  * Fix:    /fix                             |
|  * Discuss: /discuss                        |
|                                             |
+---------------------------------------------+

Progress bar calculation (20 chars): filled = round((score / 100) * 20)

Phase 7: Offer Discussion

After displaying the summary, ask the user if they want to discuss the results:

Would you like to:
1. Discuss the findings -- Ask questions, dive deeper, get clarification
2. Start fixing -- Pick an item to work on
{If Unknown items exist:}
3. Resolve unknowns -- Answer {N} quick questions to firm up your score
4. Done for now -- Review on your own later

Based on their choice:

• Discuss: Load the report context and enter discussion mode
• Start fixing: Ask which item they want to tackle first, then help fix it
• Resolve unknowns: Run the resolve-unknowns flow below
• Done: Already shown next steps in the terminal output above

Resolve-unknowns flow

Unknown items carry a -25% uncertainty deduction for things the code can't show but the user often knows (CDN-level headers, managed database backups, platform health checks). Resolving them converts uncertainty into real signal without a re-run.

1. Ask each open question from the assessor summaries, one at a time, with concrete options: Yes (it's in place), No (it's not), Not sure. Batch related questions where natural — this should take the user under a minute.
2. Apply answers:
   • Yes → Pass: delete the checklist item file, set the item's status to Pass in metadata, remove the deduction
   • No → Fail: update the item file's Status to Fail, add a note **Resolved:** {date} — confirmed missing by user, and apply the Fail deduction for the item's priority (per reference/scoring.md)
   • Not sure: leave as Unknown, keep the -25% deduction
3. Recompute adjustedEarned, score, and band per reference/scoring.md. Re-check the critical gate.
4. Update metadata.json, summary.md, report.md, action-plan.md, and checklist/index.md to match.
5. Re-display the score banner with the new score, noting the change (e.g., Score: 78/100 (was 74 — 3 unknowns resolved)).

Resolved answers are user-confirmed facts, not code evidence. Record them in metadata.json under resolvedUnknowns so a future /refresh knows the source:

"resolvedUnknowns": [
  {"id": "item-006", "answer": "yes", "date": "{YYYY-MM-DD}"}
]

Score Bands

• 90-100: Production Ready -- Ship confidently
• 75-89: Launch Ready -- Safe for early users
• 60-74: Needs Work -- Gaps that will bite you
• 0-59: Early Stage -- Not safe for real users

N/A items are excluded from the scoring pool. A project with 4 N/A items is scored against the remaining applicable items only.

Critical gate: If any item has status=Fail and priority=Critical, the band is capped at "Needs Work" regardless of score. Critical issues prevent Production Ready / Launch Ready status.

Orchestrator Rules

Stay lean. You are a coordinator, not a worker.

Delegate exploration. Never glob/grep/read extensively yourself. That's the mapper's job.

Delegate evaluation. Never assess domains yourself. That's the assessors' job.

Write final files. Summary, report, action-plan, index -- these are your job because they aggregate agent outputs.

Keep agents focused. Each agent has one job. Don't ask them to do extra work.

Trust agent outputs. Don't second-guess or re-evaluate. Agents have the full context you delegated.

Context