Skip to main content

/dev-verify

Validate integrated build pipeline and running services with health checks and smoke tests.

Overview​

Answers the single question: "Does my project work?" Combines build verification (compile, type-check, auto-fix) and runtime verification (health checks, contract validation, smoke tests) into one command. Reads tech.md to detect your stack, then runs a three-phase pipeline: analysis, build verification, and runtime verification.

Supports Node.js/TypeScript, PHP, and Go out of the box. Handles monorepos (Turborepo, pnpm workspaces), ORM generate steps (Prisma, Drizzle), Docker Compose services, and database/cache health checks.

Usage​

/dev-verify
/dev-verify --build-only
/dev-verify --runtime-only
/dev-verify --skip-smoke --skip-fix
/dev-verify --port 4000
FlagDescription
--build-onlySkip runtime verification. Only compile/type-check.
--runtime-onlySkip build verification. Only health checks.
--skip-smokeSkip smoke tests in runtime phase.
--skip-fixReport build errors without auto-fixing.
--port PORTOverride default port for a service.

When run without flags, executes the full pipeline (build + runtime).

What It Produces​

Files at $JAAN_OUTPUTS_DIR/dev/verify/{id}-{slug}/:

FileContent
{id}-{slug}.mdVerification report with build results, health check results, and recommendations

What It Asks​

QuestionWhenWhy
Verification strategy approvalAfter Phase 1 analysisConfirm detected stack and planned checks
Build-only / Runtime-onlyAt HARD STOPUser may want to narrow scope
Write endpoint approvalBefore smoke-testing POST/PUT/DELETEPrevent unintended data changes

Three-Phase Workflow​

Phase 1 — Analysis (Read-Only)​

  1. Reads tech.md to detect backend, frontend, package manager, ORM, database, and cache
  2. Reads integration manifest (if available from dev-output-integrate)
  3. Discovers project state: dependency manifests, monorepo structure, ORM configs
  4. Discovers API contracts (OpenAPI specs)
  5. Presents verification plan at HARD STOP for approval

Phase 2 — Build Verification​

  1. Installs dependencies
  2. Runs ORM generate (Prisma, Drizzle, sqlc, wire) if applicable
  3. Runs type/compile check (tsc, phpstan, go vet)
  4. Categorizes errors into generic categories
  5. Auto-fixes safe errors (missing deps, export mismatches, config gaps)
  6. Re-runs build pipeline to verify fixes

Build error categories:

CategoryAuto-Fix?
missing-dependencyYes
export-import-mismatchYes
type-mismatchConditional (simple casts only)
schema-driftNo (report only)
config-mismatchYes

Phase 3 — Runtime Verification​

  1. Checks port availability for each service
  2. Runs HTTP health checks against detected endpoints
  3. Runs database/cache health commands (pg_isready, redis-cli PING, etc.)
  4. Validates API responses against OpenAPI contract (if spec found). When Spectral and/or Prism are available locally, enhanced contract validation runs automatically: Spectral lints the spec for style conformance and Prism validates response payloads against schema definitions
  5. Runs smoke tests on GET endpoints (write endpoints require approval)
  6. Cross-validates build and runtime results

Workflow Chain​

/dev-output-integrate + /dev-project-assemble
  |
  v
/dev-verify  (build + runtime)
  |
  v
/devops-deploy-activate

Example​

Input:

/dev-verify

Output:

Mode:        Full (build + runtime)
Build:       PASS (3 errors found, 3 auto-fixed)
Runtime:     PASS (4/4 services healthy)
Contract:    PASS (12 endpoints validated)
Smoke Tests: PASS (8 GET endpoints tested)

Report: jaan-to/outputs/dev/verify/42-my-project-verify/42-my-project-verify.md

Tips​

  • Run after dev-output-integrate or dev-project-assemble to verify everything works together
  • Use --build-only for fast compile checks during development
  • Use --runtime-only when services are already running and you just need health validation
  • Use --skip-fix to get a report without any auto-modifications
  • Keep services running before invoking — this skill does not start or stop services
  • curl is restricted to localhost only — no external requests

Technical Details​

  • Logical Name: dev-verify
  • Command: /dev-verify
  • Role: dev
  • Output: $JAAN_OUTPUTS_DIR/dev/verify/{id}-{slug}/
  • Multi-Stack: Node.js/TypeScript, PHP, Go
  • Closes: #78, #85