fogserv.cloud Workflows

Status: Active
Last Updated: August 14, 2026
Tags: workflows, runbook, planning, validation, documentation

Summary

The unified operational runbook for fogserv.cloud: how planning, implementation, validation, and documentation loop together. Every task — site feature, infra change, KB article — flows through the same four loops.

---

1. Planning Loop

1. Pick from tasks.md — the roadmap is truth. Never start work that isn't tracked there; add the task first if it's new.
2. Open a ticket / branch — GitOps is Law: every change gets a branch named after the ticket/task (feat/<slug>, fix/<slug>, kb/<slug> for documentation).
3. Scope check — confirm prerequisites are complete (see tasks.md phase gates) and identify affected surfaces: website (src/), schema (prisma/), infra, and KB entries.

2. Implementation Loop

1. Environment: dev server runs in tmux session fogserv-dev on http://localhost:5173/. Secrets come from dotenvx (.env → .env.production); never commit secrets.
2. Code standards: TypeScript strict, type-check must pass with 0 errors before handoff (bun run typecheck / tsc --noEmit). Build with NODE_OPTIONS=--max-old-space-size=4096 — default heap OOMs on SvelteKit/vite-class builds.
3. Data changes: edit prisma/schema.prisma, generate client, write a migration; update databases/schema-overview.md in the same change.
4. Small commits, real messages — one logical change per commit so rollback stays trivial.

3. Validation Loop

• Type-check passes clean (0 errors).
• Feature verified against the running dev server (manual smoke test or route-level check).
• Auth-touching changes: verify permission checks on every endpoint (register, verify-email, profile, post CRUD).
• Email-touching changes: verify webhook endpoints respond correctly without valid Mailgun credentials (dry-run mode).
• Infra changes: plan/diff reviewed before apply; drift check afterwards (see infrastructure/drift-detection.md).

4. Documentation Loop

Documentation is Memory — no change is done until it is written down:

1. KB entry: create or update the relevant /kb/ article following the store layout in README.md (Title + metadata, Summary, Context, Implementation, Next Steps, Sources & Related, Change Log).
2. Change Log: append a timestamped entry describing what changed and which ticket/session triggered it.
3. Cross-link: point to at least one related KB article; update the directory map if a new topic was created.
4. Session log: record insights in lessons-learned.md and any bug + root cause in problems-solved.md.
5. Handoff: if ending a session mid-phase, update tasks.md Quick Status and add a dated Change Log entry describing where the next agent should pick up.

Related

• TELOS — pillars behind these loops
• tasks — current roadmap state
• agent — full operating context
• implementations — architecture decisions
• README — KB store layout

Change Log

• 2026-08-14 — Created workflows.md; file was referenced by README.md, index.md, and tasks.md but had never been written (audit finding). Content reconstructed from tasks.md session logs and TELOS mandates.
• Phase 6 (Staging/Rollback/Backup): see kb/artifacts/phase6/staging-rollback-backup.md — GitOps staging deploy workflow, rollback runbook with kubectl undo + git revert, restic-to-MinIO backup script + systemd timer.