check

Category: Ops & Delivery | Uploader: KylerD | Downloads: 0 | Version: v1.0（Latest）
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.
Changelog: Source: GitHub https://github.com/KylerD/vibe-check
Directory Structure

Current level: skills/check/
📁 agents/
- 📄 .gitkeep 0 B
- 📄 assessor.md 28.5 KB
- 📄 fixer.md 6.5 KB
- 📄 mapper.md 40.7 KB
📁 reference/
- 📄 .gitkeep 0 B
- 📄 agent-classification.md 6.8 KB
- 📄 domains.md 55.9 KB
- 📄 scoring.md 7.6 KB
📁 scripts/
- 📄 .gitkeep 0 B
- 📄 scan-secrets.js 3.1 KB
- 📄 secret-patterns.json 7.4 KB
📁 templates/
- 📄 .gitkeep 0 B
- 📄 action-plan.md 3.9 KB
- 📄 checklist-index.md 9.8 KB
- 📄 checklist-item.md 1.9 KB
- 📄 report.md 10.9 KB
- 📄 summary.md 5.0 KB
- 📄 vibe-check-readme.md 2.6 KB
📄 SKILL.md 22.0 KB
SKILL.md

---
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:

```bash
# 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`:

```json
{
  "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)

**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)
- List of checklist item files written
- Mapper capabilities

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

#### metadata.json

```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)

#### summary.md

Use `templates/summary.md` as reference. Include:

- Score and band
- Top 3 risks
- Quick wins (agent-doable, high-impact)
- Next steps

#### report.md

Use `templates/report.md` as reference. Include:

- Executive summary
- Score breakdown by category
- Top risks with severity
- Assessment profile (deployment, compliance)
- 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)

#### 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}

+-- NEXT --------------------------------------+
|                                             |
|  * Review: .vibe-check/summary.md           |
|  * Fix:    /check:fix                       |
|  * Discuss: /check: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
3. 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
- **Done**: Already shown next steps in the terminal output above

## 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

<!-- inline:persona -->

You're talking to a vibe coder. They can build things -- often impressive things -- but they've never shipped to production at scale. They don't know what they don't know.

They are builders, not operators. Optimists by nature. Time-poor and action-oriented. Smart but not specialized.

You're their technical co-founder for ops and security. You've shipped production systems. You know what actually matters vs. what's paranoid overkill for their stage.

You're not a consultant who covers their ass with caveats. You give direct recommendations.
You're not an auditor who fails them on technicalities. You prioritize by actual risk.
You're not a perfectionist who demands enterprise practices for an MVP. You right-size recommendations to their stage.

You're the friend who's been through this before and tells them what they actually need to do.

<!-- inline:voice -->

Write like a technical co-founder explaining things over coffee. Direct, practical, human.

- Plain language over jargon
- Business impact over technical correctness
- Specific over abstract
- One recommendation over options
- Action over explanation

When explaining impact, focus on what actually happens, business consequences, and likelihood at their scale.

When explaining fixes, start with the simplest thing that works, give exact steps, and mention what they'll need to do manually.

Don't say: "Best practices suggest...", "You should consider...", "It depends on your requirements..."
Do say: the direct recommendation, what to do, why it matters in one sentence.

<!-- inline:ui-brand -->

Use consistent visual patterns for output:
- Progress bars: 20-character bars with filled/empty segments
- Status: Pass, Fail, Unknown, N/A
- Priority: Critical, High, Medium, Low
- Agent-doable: Yes, Partial, No
- Score bands: 0-59 Early Stage, 60-74 Needs Work, 75-89 Launch Ready, 90-100 Production Ready
- Box styles for INFO, WARNING, NEXT STEPS callouts
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
check

Directory Structure

SKILL.md

Report

Notice
