project-readiness - SKILL.md Agent Skill

name: project-readiness description: Verify a project is ready for release by checking local Docker Compose startup, Kubernetes manifest sanity, GitHub Actions status via gh, and test/coverage commands. Use when the user asks to confirm readiness, pre-release checks, a release checklist, or to diagnose why CI/build/deploy is failing right before release.

Project Readiness

Perform a practical pre-release checklist against the current repo state.

This skill is optimized for repos generated by project-bootstrap (expected paths: docker/docker-compose.yml, deploy/, k8s/, scripts/reset-docker.sh, core/, portal/), but should degrade gracefully if some parts are missing.

Workflow (Always)

Snapshot state

git status --porcelain
Identify changed files that may affect runtime: docker/, deploy/, k8s/, core/, portal/, .github/workflows/.

Local Docker Compose readiness

Bring up services, confirm they are healthy/running, and check logs for obvious errors.
If dirty state is likely (flaky behavior, migrations, or repeated failures), reset first.

Tests and coverage readiness

Run project-defined unit tests for backend and frontend.
If coverage is a requirement, run the project's coverage command(s) and ensure targets are met.

Kubernetes readiness (sanity checks)

Validate manifests can be rendered/applied (dry-run) and that rollout commands exist.

GitHub Actions readiness (via gh)

Fetch latest run for the default branch and report pass/fail.
On failure, pull logs, summarize the root cause, and propose a fix.

Use the bundled script for the local checks when possible.

Local Readiness Script

Run:

.claude/skills/project-readiness/scripts/check_local.sh

Environment:

COMPOSE_FILE (default: docker/docker-compose.yml)
CORE_HOST_PORT / PORTAL_HOST_PORT (optional): override host port bindings if defaults are already in use
RESET_FIRST=true (optional): run ./scripts/reset-docker.sh first if present
LOG_TAIL (default: 200)

GitHub Actions Check (gh)

Requirements:

gh installed and authenticated to the repo.

Commands:

gh auth status
gh run list -L 1
gh run view <run_id> --log

If gh auth status fails, ask the user to log in (gh auth login) or provide a run URL/id to inspect.

If gh commands fail due to sandbox restrictions, request escalated permissions before retrying.

Kubernetes Sanity Checks

If k8s/base/ exists:

Avoid kubectl apply --dry-run=client validations if the current kubeconfig context points at an unreachable cluster (it can still attempt discovery/validation). Prefer offline checks:

kubectl kustomize k8s/base >/dev/null

If you must run kubectl apply style checks, consider using a reachable context first, or pass --validate=false and clearly note that you are skipping schema validation.

If kubectl commands fail due to sandbox restrictions, request escalated permissions before retrying.

If deploy/ scripts exist:

Prefer ./deploy/deploy.sh --dry-run and ./deploy/upgrade.sh --dry-run if supported.

Output Expectations

Report a readiness summary with:

Docker Compose: PASS/FAIL + key error snippet if failed
Tests: PASS/FAIL + failing command
K8s: PASS/FAIL + failing validation
GitHub Actions: PASS/FAIL + latest run link/id + failing step summary

If anything fails, provide:

Most likely root cause
Smallest fix plan
What to rerun to confirm