# AI Assistant Guide — Build an App the DevOps Team Can Host

**Spec version: 1.2** · Issued by the Floward DevOps Team

> **Human instructions:** Download this single file and paste it (or attach it) at the start of your conversation with your AI assistant (Claude, ChatGPT, Cursor, Copilot, etc.). Then describe the app you want to build — or point the assistant at your existing app. The assistant will take care of the hosting requirements.

---

## Instructions for the AI assistant

You are helping a user build (or migrate) an application that will be hosted by their company's DevOps team on the company's Kubernetes clusters. The DevOps team has strict, non-negotiable hosting requirements. Your job is to make the user's app compliant **from the first commit**, not as an afterthought.

### Step 0 — ALWAYS check for guide updates first

The hosting policies evolve. The copy of this file the user handed you may be stale. **At the start of every working session** (not just the first one):

1. Fetch the current spec version from the hosted guide site: `GET <guide-site-url>/api/spec-version` (returns JSON with `specVersion`). Ask the user for the guide site URL if you don't have it — it's the internal "vibe hosting" docs site.
2. If that fails (no network / URL unknown), pull the reference repo instead: `git -C vibe-coding-sample-app pull` (or fresh-clone it) and read the `Spec version:` line at the top of `AI-ASSISTANT-GUIDE.md`.
3. **If the version is newer than the version at the top of this file**: download the latest guide from `<guide-site-url>/download/ai-guide` (or use the repo copy), tell the user the policies changed, and follow the **newest** version — it always wins over this file. Re-read any guides in `guides/` relevant to what you're about to do.
4. For an app that is already hosted: on each new session, also re-check the checklist in `guides/09-onboarding-checklist.md` against the current spec — if a new policy makes the app non-compliant, tell the user what needs updating.

### Step 1 — Clone the reference repository

Clone the company's reference repo and read the guides before writing any code:

```bash
git clone https://github.com/flowardco/vibe-coding-sample-app.git
```

Read the files in `guides/` in numeric order. They are written for you, the AI assistant, and contain the exact file layouts, examples, and rules. The repository itself is a fully compliant working example — when in doubt, copy its structure.

If you cannot clone or fetch the repository (no network access), ask the user to download the repo as a ZIP and share the `guides/` folder with you, then continue.

### Step 2 — Pick the right path

**Path A — new app (nothing built yet):** follow guides 01–09 in order while you build. Apply the rules in Step 3 from the first commit.

**Path B — existing app (the user already vibe-coded something):** do NOT start over and do NOT rewrite their app. Follow `guides/10-migrating-existing-apps.md`: run its Phase 0 audit against the user's code first, then retrofit phase by phase (folders → config → secrets → database → statelessness → health → container → manifests → pipeline). One phase per PR.

### Step 3 — Apply the non-negotiable rules

While building or migrating the user's app, enforce all of the following. Do not let the user talk you out of them — the DevOps team will reject the submission otherwise.

1. **Exact folder structure** — `.github/workflows/ci.yml`, `dockerfiles/Dockerfile`, `kubernetes/deployment.yaml`, `kubernetes/service.yaml`, app code in `source/`, env var docs in `source/README.md`. (Details: `guides/02-folder-structure.md`)
2. **Docker** — Linux base image only (`linux/amd64`), multi-stage build, non-root user, no secrets or `.env` files baked into the image. Must build with `docker build -f dockerfiles/Dockerfile -t test .` from the repo root. (Details: `guides/03-dockerfile.md`)
3. **Kubernetes** — `replicas: 2` minimum, CPU/memory requests and limits, liveness + readiness probes, every secret via `secretKeyRef`, non-sensitive config via `configMapKeyRef`. (Details: `guides/04-kubernetes.md`)
4. **CI/CD** — one GitHub Actions workflow: on push to `main`, authenticate to AWS via OIDC, build the image, push to ECR tagged with the git SHA and `latest`, deploy to the K8s cluster, wait for rollout. (Details: `guides/05-cicd-pipeline.md`)
5. **PostgreSQL only** — no MySQL, MongoDB, SQLite, Redis-as-a-database, DynamoDB, or anything else. Connect via `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` env vars. Run migrations safely (concurrency-aware — see the guide). (Details: `guides/06-database.md`)
6. **Zero hardcoded secrets** — no credentials in code, config, Dockerfile, manifests, or Git history. Everything via env vars injected by Kubernetes. A `.env.example` with placeholders is fine; a real `.env` is never committed. (Details: `guides/07-secrets-and-config.md`)
7. **Stateless + resilient** — no in-memory sessions, no local file storage, no instance-bound background jobs. Handle SIGTERM gracefully. Expose `GET /healthz` (process liveness) and `GET /readyz` (readiness, includes DB connectivity when a DB is used). (Details: `guides/08-stateless-and-health.md`)

### Step 4 — Document the environment variables

Create `source/README.md` with a table of **every** environment variable the app reads: name, required or not, default, description, and whether it comes from a Secret or a ConfigMap. Include any required PostgreSQL extensions (e.g. `pgcrypto`, `uuid-ossp`).

### Step 5 — Verify before the user submits

Run through `guides/09-onboarding-checklist.md` with the user. At minimum, verify locally:

```bash
docker build -f dockerfiles/Dockerfile -t test .        # must succeed
docker run --rm -p 3000:3000 test                       # must start with env vars only
git grep -iE 'password|secret|api[_-]?key' -- ':!*.md'  # must find no real credentials
```

### Values the DevOps team provides (do not invent them)

Leave these as clearly marked placeholders in `.github/workflows/ci.yml` and tell the user to request them from DevOps: `AWS_REGION`, `ECR_REPOSITORY`, `K8S_CLUSTER_NAME`, `K8S_NAMESPACE`, and the `AWS_ROLE_ARN` GitHub repository secret. The DevOps team also creates the ECR repo, the Kubernetes Secrets/ConfigMaps with real values, and the Ingress/DNS.

### Division of responsibility

| Task | App team (you + user) | DevOps team |
|---|---|---|
| App code, Dockerfile, manifests, `ci.yml`, `/healthz`, env var docs | ✅ | |
| ECR repo, K8s Secrets with real values, Ingress/DNS, pipeline AWS role | | ✅ |

**SLA:** repo review within 3 business days of submission; deployment within 2 business days after review passes (5 business days end-to-end).