Shipkit Scale Ready

shipkit-scale-ready - Scale Readiness Audit

Purpose: Ensure your production system can handle growth and be operated reliably.

Who this is for: Teams with traction — you've launched, you have users, now you need to harden for scale.

Prerequisite: Preflight passed. This skill assumes MVP-level production readiness already exists.

When to Invoke

User triggers:

• "Ready to scale"
• "Scale readiness check"
• "Production hardening"
• "Post-MVP audit"
• "We have traction, what should we fix?"
• "Enterprise readiness"

Workflow position:

• After MVP launch and user traction
• Before scaling marketing/growth efforts
• Before enterprise customers
• When transitioning from "it works" to "it's robust"

The Two Tiers

Default audit covers Growth tier. Enterprise tier on request or if context indicates enterprise customers.

Process

Completion Tracking

After determining scope, create tasks per audit category:

• TaskCreate for each applicable category (Security/DB, Observability/Perf, Reliability/Ops, Code Maturity, Compliance)
• TaskCreate: "Merge all subagent results"
• TaskCreate: "Write scale-readiness.json"
• TaskCreate: "Archive previous audit (if full audit)"

TaskUpdate each task to in_progress when starting it, completed when done.

Subagent results returning is NOT done — results must be merged, classified, and written to the JSON artifact. Do NOT skip the archive step.

Step 0: Verify Prerequisites

1. Check if preflight passed recently
   - Read .shipkit/preflight.json
   - If blockers exist: "Fix preflight blockers first — run /preflight"

2. Load project context
   - .shipkit/stack.json — tech stack
   - .shipkit/why.json — scale expectations
   - .shipkit/architecture.json — key patterns

Step 1: Determine Audit Scope

Check for previous scale audit:

1. Check if .shipkit/scale-readiness.json exists
2. If exists, get changes since last audit
3. Determine: FULL AUDIT vs INCREMENTAL

Map stack to relevant categories:

Step 2: Run Checklist by Category

For each applicable category, run checks and classify as:

• ✅ Pass — Implemented correctly
• ⚠️ Warning — Partially implemented or could improve
• ❌ Fail — Missing or broken
• ⏭️ N/A — Not applicable to this stack
• 👤 Human-Verify — Claude cannot verify, human must check

See: references/checklists/ for detailed check definitions.

Index-Accelerated Audit — Read .shipkit/codebase-index.json first:

1. Read: .shipkit/codebase-index.json
2. If index exists:
   • Use framework to skip N/A categories (e.g., skip database checks if no DB in stack)
   • Use concepts to direct each agent to relevant files
   • Use configFiles to identify what infrastructure is configured
   • Use coreFiles for prioritizing high-impact audit targets
3. If index doesn't exist → agents scan entire codebase as below

USE PARALLEL SUBAGENTS BY CATEGORY - For full audits, spawn multiple Explore agents in parallel:

Launch these Agent subagents IN PARALLEL (single message, multiple tool calls):

1. SECURITY & DATABASE AGENT (subagent_type: "Explore")
   Prompt: "Audit security hardening and database optimization in this [stack] codebase.
   [If index exists, include: 'Start from: auth=[concepts.auth files], database=[concepts.database files]. Config: [configFiles].']
   SECURITY: Check security headers (CSP, HSTS), session config, admin route protection,
   re-auth on sensitive actions, API key management.
   DATABASE: Check indexes on queries, N+1 patterns, connection pooling, slow query logging.
   Report Pass/Fail/Warning/Human-Verify with file:line evidence for each check."

2. OBSERVABILITY & PERFORMANCE AGENT (subagent_type: "Explore")
   Prompt: "Audit observability and performance in this [stack] codebase.
   [If index exists, include: 'Entry points: [entryPoints]. Core files: [coreFiles]. Recently active: [recentlyActive].']
   OBSERVABILITY: Check structured logging vs console.log, log levels, request/correlation ID,
   error tracking context, health endpoint detail.
   PERFORMANCE: Check bundle size, code splitting, image optimization, caching headers,
   API response caching.
   Report Pass/Fail/Warning/Human-Verify with file:line evidence for each check."

3. RELIABILITY & OPERATIONS AGENT (subagent_type: "Explore")
   Prompt: "Audit reliability patterns and operational readiness in this [stack] codebase.
   [If index exists, include: 'API entry points: [entryPoints.api]. External service files: [concepts with external calls]. Config: [configFiles].']
   RELIABILITY: Check timeouts on external calls, retry with backoff, graceful degradation,
   idempotency keys, retriable jobs.
   OPERATIONS: Check for runbooks, rollback docs, zero-downtime deploy config, feature flags.
   Report Pass/Fail/Warning/Human-Verify with file:line evidence for each check."

4. CODE MATURITY AGENT (subagent_type: "Explore")
   Prompt: "Audit code maturity and technical debt in this [stack] codebase.
   [If index exists, include: 'Core files: [coreFiles]. Recently active: [recentlyActive]. Directories: [directories].']
   Check: test coverage on critical paths, duplicate components, shared component usage,
   centralized types, TODO/FIXME in core flows, dependency vulnerabilities (npm audit).
   Report Pass/Fail/Warning with file:line evidence for each check."

5. COMPLIANCE AGENT (Enterprise tier only) (subagent_type: "Explore")
   Prompt: "Audit compliance patterns in this [stack] codebase.
   [If index exists, include: 'Concepts: [concepts]. Entry points: [entryPoints]. Focus on data handling paths.']
   Check: GDPR export endpoint, GDPR deletion flow, audit logging on sensitive actions,
   data retention cleanup jobs.
   Report Pass/Fail/Warning/Human-Verify with file:line evidence for each check."

Why parallel subagents:

• Each category runs simultaneously → faster total execution
• Smaller scope per agent → more thorough checks within category
• Clear attribution → findings map directly to categories
• 8 categories × 5-6 checks each = 50+ checks parallelized efficiently

When to use parallel subagents:

• Full scale-ready audit
• Large codebase (50+ source files)

When to scan manually (single thread):

• Incremental audit (few files changed)
• Single category focus (e.g., "just check security")

The Categories

1. Security Hardening (🔶 Growth)

Beyond MVP auth — protection against targeted attacks.

🏢 Enterprise:

2. Database Optimization (🔶 Growth)

Move from "works" to "works fast at scale."

🏢 Enterprise:

3. Observability (🔶 Growth)

Can you see what's happening in production?

🏢 Enterprise:

4. Performance (🔶 Growth)

Will it handle real traffic?

🏢 Enterprise:

5. Reliability (🔶 Growth)

What happens when things fail?

🏢 Enterprise:

6. Operational Readiness (🔶 Growth)

Can you actually run and maintain this?

🏢 Enterprise:

7. Code Maturity (🔶 Growth)

Technical debt under control?

8. Compliance (🏢 Enterprise)

For enterprise customers and regulated industries.

Output Format

Output format: JSON — machine-readable by other tools, and the single source of truth for scale readiness.

Create file using Write tool: .shipkit/scale-readiness.json

Run-scoped output (parallel-safe). scale-readiness.json is a transient per-run audit, and preflight.json (read above) is too. Under the orchestration engine, resolve both under the run root (<runDir>/…) per install/shared/references/run-artifacts.md — read preflight.json from the same base preflight wrote it to; with no run context both stay at .shipkit/… (back-compatible).

The output MUST conform to the schema below. This is a strict contract — other skills depend on this structure.

JSON Schema

Full schema: See references/output-schema.md Example output: See references/example.json

Quick Reference

{
  "$schema": "shipkit-artifact",
  "type": "scale-readiness",
  "version": "1.0",
  "lastUpdated": "YYYY-MM-DD",
  "source": "shipkit-scale-ready",
  "summary": {
    "overallStatus": "scale-ready" | "needs-work" | "enterprise-ready",
    "tier": "growth" | "enterprise",
    "commit": "abc1234",
    "stack": "Next.js + Postgres",
    "counts": { "pass", "warning", "fail", "na", "human-verify" },
    "categoryScores": { "<category-id>": { counts... } }
  },
  "categories": [{
    "id", "name", "tier",
    "checks": [{ "id", "name", "status", "severity", "details", "evidence?", "recommendation?" }]
  }],
  "blockers": [{ "checkId", "category", "name", "severity", "details", "evidence?", "recommendation" }]
}

Key Fields

Context Files This Skill Reads

Required:

• .shipkit/preflight.json — Preflight must have passed
• .shipkit/stack.json — Tech stack

Recommended:

• .shipkit/why.json — Scale expectations
• .shipkit/architecture.json — Patterns and decisions
• .shipkit/engineering-definition.json — Mechanisms, components, design decisions
• .shipkit/scale-readiness.json — Previous audit (for incremental)

Scans:

• Source code for patterns
• Config files (CI/CD, Docker, etc.)
• Documentation (runbooks, etc.)

Context Files This Skill Writes

Write Strategy: OVERWRITE

Creates/Updates:

• .shipkit/scale-readiness.json — Structured scale readiness audit (JSON artifact)

Update Behavior:

• File exists → Load previous audit, determine FULL vs INCREMENTAL
• Full audit → Archive old version first, then overwrite
• Incremental → Read existing, update changed categories only
• Each write REPLACES entire file contents

Archives (on full audit):

• .shipkit/.archive/scale-readiness-[YYYY-MM-DD].json

Shipkit Artifact Convention

This skill follows the Shipkit JSON artifact convention. See references/output-schema.md for full documentation.

Relationship to Other Skills

After Completion

Scale readiness audit written to .shipkit/scale-readiness.json.

Next:

• If critical blockers present: fix them, then re-run /shipkit-scale-ready to confirm they clear.
• If scale-ready or warnings only: run /shipkit-preflight (and then /shipkit-review-shipping) as the pre-ship gate before each deploy — preflight reads .shipkit/scale-readiness.json to skip re-checking what's already hardened.

Scale-ready is a periodic system-wide hardening audit; preflight and review-shipping are the per-release gates. Re-run scale-ready when entering a new growth tier (more traction, enterprise customers) or after major architectural change.

Success Criteria

• Preflight status verified (passed)
• Stack context loaded
• Tier determined (Growth vs Enterprise)
• All applicable categories checked
• Human-verify items clearly listed
• Evidence provided for each finding
• Prioritized output (critical → improvements → passed)
• Output conforms to JSON schema above
• Summary field is accurate (in sync with categories)
• Report saved to .shipkit/scale-readiness.json