coding-os 0.3.2__py3-none-any.whl

core/skills/task-driver/scripts/task-lint.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# Lint one or more TASK-NNN-slug.md files for Scrumban discipline.
+#
+# Checks:
+#   - Frontmatter: id, title, status, swimlane, kind exist + valid values
+#   - Required body sections: Outcome, Read First, Acceptance
+#   - Body size: warn > 1.5K bytes, block > 3K (Rule 14: tasks are pointers, not specs)
+#   - Internal links resolve (relative paths exist)
+#
+# Usage:
+#   bash task-lint.sh docs/tasks/TASK-NNN-slug.md
+#   bash task-lint.sh docs/tasks/                  # lint a directory
+#   bash task-lint.sh --json docs/tasks/
+#
+# Exit codes:
+#   0 = all clean
+#   1 = warnings only (size or recoverable)
+#   2 = hard error (missing required fields)
+
+set -euo pipefail
+
+# Safety: ensure core POSIX tools resolvable even when caller PATH is restricted.
+export PATH="/usr/bin:/bin:/usr/local/bin:${PATH:-}"
+
+EMIT_JSON=0
+TARGETS=()
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --json) EMIT_JSON=1; shift ;;
+    -h|--help) sed -n '2,14p' "$0"; exit 0 ;;
+    *) TARGETS+=("$1"); shift ;;
+  esac
+done
+
+if [ "${#TARGETS[@]}" -eq 0 ]; then
+  echo "usage: $0 [--json] <task.md | tasks-dir> ..." >&2
+  exit 2
+fi
+
+# Expand directories to .md files
+FILES=()
+for t in "${TARGETS[@]}"; do
+  if [ -d "$t" ]; then
+    while IFS= read -r f; do
+      FILES+=("$f")
+    done < <(find "$t" -maxdepth 1 -name "TASK-*.md" -type f | sort)
+  elif [ -f "$t" ]; then
+    FILES+=("$t")
+  else
+    echo "Not found: $t" >&2
+    exit 2
+  fi
+done
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  echo "No TASK-*.md files found in inputs" >&2
+  exit 2
+fi
+
+VALID_STATUS="^(backlog|in_progress|testing|blocked|complete|archived)$"
+VALID_SWIMLANE="^(backend|frontend|mobile|docs|meta|ops|infra|cross)$"
+VALID_KIND="^(feat|fix|chore|refactor|docs|test|spike)$"
+
+declare -i exit_code=0
+declare -a FINDINGS=()
+
+# JSON helper: emit a finding tuple
+add_finding() {
+  local file="$1" sev="$2" msg="$3"
+  FINDINGS+=("$file|$sev|$msg")
+  if [ "$sev" = "ERROR" ]; then exit_code=2; fi
+  if [ "$sev" = "WARN" ] && [ "$exit_code" -lt 1 ]; then exit_code=1; fi
+}
+
+extract_fm_field() {
+  local file="$1" field="$2"
+  awk -v field="$field" '
+    BEGIN { in_fm=0 }
+    /^---$/ { in_fm = !in_fm; if (in_fm == 0) exit; next }
+    in_fm == 1 && $0 ~ "^"field":" {
+      sub("^"field":[ \t]*", "")
+      gsub("\"", "")
+      print
+      exit
+    }
+  ' "$file"
+}
+
+has_section() {
+  local file="$1" heading="$2"
+  grep -qE "^##[ ]+${heading}\b" "$file"
+}
+
+for f in "${FILES[@]}"; do
+  # Frontmatter checks
+  if ! head -1 "$f" | grep -qE "^---$"; then
+    add_finding "$f" "ERROR" "missing frontmatter (no leading '---')"
+    continue
+  fi
+
+  id=$(extract_fm_field "$f" "id" || true)
+  status=$(extract_fm_field "$f" "status" || true)
+  swimlane=$(extract_fm_field "$f" "swimlane" || true)
+  kind=$(extract_fm_field "$f" "kind" || true)
+  title=$(extract_fm_field "$f" "title" || true)
+
+  [ -z "$id" ] && add_finding "$f" "ERROR" "frontmatter missing 'id'"
+  [ -z "$title" ] && add_finding "$f" "ERROR" "frontmatter missing 'title'"
+  [ -z "$status" ] && add_finding "$f" "ERROR" "frontmatter missing 'status'"
+  [ -z "$swimlane" ] && add_finding "$f" "WARN" "frontmatter missing 'swimlane'"
+  [ -z "$kind" ] && add_finding "$f" "WARN" "frontmatter missing 'kind'"
+
+  if [ -n "$status" ] && ! [[ "$status" =~ $VALID_STATUS ]]; then
+    add_finding "$f" "ERROR" "invalid status '$status' (must be: backlog|in_progress|testing|blocked|complete|archived)"
+  fi
+  if [ -n "$swimlane" ] && ! [[ "$swimlane" =~ $VALID_SWIMLANE ]]; then
+    add_finding "$f" "WARN" "invalid swimlane '$swimlane'"
+  fi
+  if [ -n "$kind" ] && ! [[ "$kind" =~ $VALID_KIND ]]; then
+    add_finding "$f" "WARN" "invalid kind '$kind'"
+  fi
+
+  # Body required sections
+  has_section "$f" "Outcome" || add_finding "$f" "ERROR" "missing '## Outcome' section"
+  has_section "$f" "Read First" || add_finding "$f" "WARN" "missing '## Read First' section"
+  has_section "$f" "Acceptance" || add_finding "$f" "ERROR" "missing '## Acceptance' section"
+
+  # Size (Rule 14)
+  bytes=$(wc -c < "$f" | tr -d ' ')
+  if [ "$bytes" -gt 3000 ]; then
+    add_finding "$f" "ERROR" "body size ${bytes}B > 3K — tasks are pointers, not specs (Rule 14)"
+  elif [ "$bytes" -gt 1500 ]; then
+    add_finding "$f" "WARN" "body size ${bytes}B > 1.5K — consider linking to a spec doc instead"
+  fi
+done
+
+# Emit
+if [ "$EMIT_JSON" -eq 1 ]; then
+  printf '['
+  first=1
+  for entry in "${FINDINGS[@]+"${FINDINGS[@]}"}"; do
+    file="${entry%%|*}"; rest="${entry#*|}"
+    sev="${rest%%|*}"; msg="${rest#*|}"
+    [ $first -eq 0 ] && printf ','
+    printf '\n  {"file": "%s", "severity": "%s", "message": "%s"}' "$file" "$sev" "$(echo "$msg" | sed 's/"/\\"/g')"
+    first=0
+  done
+  printf '\n]\n'
+else
+  if [ "${#FINDINGS[@]}" -eq 0 ]; then
+    echo "[task-lint] OK: ${#FILES[@]} task file(s) clean."
+  else
+    echo "[task-lint] ${#FINDINGS[@]} finding(s) across ${#FILES[@]} file(s):"
+    for entry in "${FINDINGS[@]}"; do
+      file="${entry%%|*}"; rest="${entry#*|}"
+      sev="${rest%%|*}"; msg="${rest#*|}"
+      printf "  [%-5s] %s — %s\n" "$sev" "$file" "$msg"
+    done
+  fi
+fi
+
+exit "$exit_code"

core/skills/technical-writing/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: technical-writing
+tier: quality
+domain: [universal]
+description: Write documentation, READMEs, ADRs, runbooks, commit/PR bodies, and code comments that a reader acts on without re-reading. Use when authoring or reviewing any prose deliverable — a playbook, a spec, an API doc, a migration note, a release changelog, or an in-code comment. Enforces altitude (right level of detail), active voice, one-idea-per-section, specificity over vagueness, the coding-os doc-header + P/R/S/N navigation contract, and comments-as-failure-signal. Triggers — "write docs", "document this", "README", "ADR", "runbook", "explain in the docs", "write a comment", any `docs/**/*.md`. Pairs with clean-code (comments), task-driver (task prose), api-design (contract docs).
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+---
+
+# Technical Writing
+
+Docs are the contract (Rule 0/19) — code follows prose, not the reverse. A doc that buries its point, mixes altitudes, or restates the code is worse than no doc: it costs every future reader the time to discover it's useless. This skill makes "a reader acts on it the first time" the bar.
+
+> Scaffold a doc with the house header already correct:
+> `python3 scripts/new_doc.py --layer playbook --domain BACKEND --title "Service X runbook" --root docs/playbooks`
+
+> **The doc *system* — taxonomy, layers, naming, header rules — is governed by
+> [docs/governance/docs-system.md](../../../docs/governance/docs-system.md) (SSOT).**
+> This skill is the *craft* layer on top: how to write each layer *well*.
+
+## The five craft rules
+
+1. **Altitude — match detail to the reader's decision.** An index routes; a playbook sequences; a reference exhausts; an ADR justifies. Don't put reference-grade tables in a playbook, or hand-wave in a spec. Ask "what does the reader decide here?" and write exactly that.
+2. **One idea per section.** A heading is a promise. If a section covers two things, split it. The reader scans headings first — they must predict content.
+3. **Active voice, present tense, specific subject.** "The hook blocks the write" not "the write may be blocked". Name the actor.
+4. **Specificity over vagueness.** "completes in <50 ms on the highest-degree hub" beats "is fast". Numbers, file paths, exact commands — never "appropriately" or "as needed".
+5. **Bad→good for every rule.** Show the failure and the fix. Prose advice the reader can't anchor to an example is weak.
+
+Full sentence/paragraph craft → [references/writing-craft.md](references/writing-craft.md).
+
+## The coding-os doc-header + navigation contract
+
+Every active doc opens with a machine-readable header + nav block; `regen_doc_index.py` depends on it — malformed, and the doc is invisible to its index. The **canonical field spec is owned by [docs/governance/docs-system.md](../../../docs/governance/docs-system.md)** (it ships to every project); don't carry a second copy. Or scaffold it correctly with `new_doc.py`. Shape, for orientation:
+
+```markdown
+<!-- domain:BACKEND | layer:playbook | ssot:true | updated:2026-06-04 -->
+# Title
+
+Purpose: <one line>.
+Read when: <trigger>.
+Skip when: <when another doc is right>.
+Read next: [related](related.md)
+
+> Nav: [Section Index](./00-index.md) | [Docs Index](../00-index.md)
+```
+
+The compact `> P/R/S/N` form is the same contract inside a skill. Per-layer "what good looks like" → [references/doc-anatomy.md](references/doc-anatomy.md).
+
+## Comments — a comment is a failure signal
+
+```python
+# Wrong — restates the code, rots on the next edit
+i += 1   # increment i
+
+# Correct — explains the non-obvious WHY the code can't
+i += 1   # skip the sentinel row the loader prepends (see loader.py:42)
+```
+
+Rule 12: comments by exception, not default. If a comment explains *what*, delete it and rename until the code says what. Keep comments that explain *why* — a constraint, a workaround, a non-obvious invariant. The best comment is a better name.
+Clean code should be readable enough not to need comments.
+
+A comment never carries provenance — no task IDs (`TASK-123`), phase/plan labels (`Phase 2`, `P5:`), or gate codes (`(G9)`, `(E1)`). `git blame` records who/what; the comment records the timeless *why*. Strip the ID, keep the reason. Same rule kills `TODO`/`FIXME` in committed code: file a task, don't leave a marker.
+
+## Commit & PR prose
+
+Commit title ≤100 chars, body ≤3 lines explaining *why* (Rule 24 — enforced). Verbose audit tables, file lists, and verification logs belong in the PR description, the audit doc, or the work-log — never `git log`. A PR body carries the *what changed and why it's safe*; a commit carries the *one-line intent*.
+
+## Anti-patterns (reject on sight)
+
+- A wall of prose with no headings — the reader can't scan.
+- "This document describes…" preamble — start with the point.
+- Reference tables inside a playbook (wrong altitude) — link a reference.
+- A comment that restates the line below it.
+- A comment tagging the task/phase/gate that introduced the change (`# TASK-123`, `# Phase 2`) — provenance lives in `git blame`, not the source.
+- "Should", "appropriately", "as needed", "various", "etc." carrying real meaning — be specific.
+- Duplicating policy that already lives in `docs-system.md` — link it.
+- A new doc when an existing one has the right scope — add a section.
+
+## See also
+
+- [references/writing-craft.md](references/writing-craft.md) — sentence/paragraph craft, bad→good prose.
+- [references/doc-anatomy.md](references/doc-anatomy.md) — per-layer "what good looks like".
+- [assets/doc-checklist.md](assets/doc-checklist.md) — the ship gate.
+- [docs/governance/docs-system.md](../../../docs/governance/docs-system.md) — the doc-system SSOT (taxonomy, headers, naming).

core/skills/technical-writing/assets/doc-checklist.md

@@ -0,0 +1,29 @@
+<!-- domain:DOCS | layer:asset | ssot:false | updated:2026-06-04 -->
+# Doc Ship Checklist
+
+Run before committing any doc. Every box, or it doesn't ship.
+
+## Structure
+- [ ] Header present + correct: `<!-- domain | layer | ssot | updated:YYYY-MM-DD -->`.
+- [ ] `Purpose / Read when / Skip when / Read next` (or `> P/R/S/N`) block present.
+- [ ] `> Nav:` block links the section index + docs index.
+- [ ] Point is in the first paragraph (newspaper structure).
+- [ ] Each heading is one idea; headings alone tell the story.
+- [ ] Layer matches content (no reference tables in a playbook, no hand-waving in a spec).
+
+## Prose
+- [ ] Active voice, present tense, named subject.
+- [ ] Every "fast/slow/large" replaced with a number.
+- [ ] Every vague noun replaced with a path or symbol.
+- [ ] Hedges/intensifiers cut or justified.
+- [ ] Every rule shown bad→good where code is involved.
+- [ ] Every code claim verified against the code, not memory.
+
+## Hygiene
+- [ ] No content duplicated from another doc — linked instead.
+- [ ] New doc justified (existing doc had wrong scope) — else a section was added.
+- [ ] `python3 scripts/new_doc.py` header shape matched (if scaffolded).
+
+## Verify
+- [ ] `make docs-index-regen` lists it in the right `00-index.md`.
+- [ ] `make docs-lint` clean for this file.

core/skills/technical-writing/references/doc-anatomy.md

@@ -0,0 +1,53 @@
+<!-- domain:DOCS | layer:reference | ssot:true | updated:2026-06-04 -->
+# Doc Anatomy — What Good Looks Like Per Layer
+
+> P: How to write each coding-os doc layer *well* — the craft per taxonomy slot.
+> R: Creating or reviewing a doc and deciding what belongs in it.
+> S: The taxonomy/naming *rules* themselves — those are governed by docs-system.md.
+> N: [SKILL.md](../SKILL.md), [writing-craft.md](writing-craft.md), [docs-system.md](../../../../docs/governance/docs-system.md)
+
+> Nav: [Skill](../SKILL.md)
+
+The *rules* (header fields, file naming, where a layer lives) are SSOT in
+[docs-system.md](../../../../docs/governance/docs-system.md). This file is the
+*craft*: given the layer, what makes it good.
+
+## By layer
+
+| Layer | Job | Good looks like | Smell |
+|---|---|---|---|
+| `index` | route only | one-line entries, no content | prose paragraphs, duplicated content |
+| `playbook` | sequence a task | ordered steps + a verification block + read-selection guide | reference-grade tables inline |
+| `spec` | define requirements | testable statements ("X MUST Y"), acceptance criteria | aspirational prose, no acceptance |
+| `policy` | govern a process | the rule + the why + enforcement pointer | a rule with no rationale |
+| `reference` | exhaust a topic | complete tables, every edge case, dated | half-coverage; a "see code" hand-wave |
+| `adr` | justify a decision | context → options → decision → consequences, immutable | edited after the fact; no alternatives |
+| `task` | log one work item | pointer to specs, not inlined content (Rule 14) | a spec pasted into the task |
+
+## Header is load-bearing (why it matters)
+
+The exact header fields and the navigation contract are **owned by
+[docs-system.md](../../../../docs/governance/docs-system.md)** — do not memorize
+a second copy. The craft point: the header is not decoration. `regen_doc_index.py`
+parses the `<!-- … -->` comment, so a malformed one makes the doc invisible to
+its `00-index.md`; the `Purpose/Read-when/Skip-when` block tells the *agent*
+whether to open the doc before spending tokens. Get either wrong and the doc
+exists but no one finds it.
+
+## Skeletons — start from the canonical template
+
+Don't hand-build a layer's structure — every layer has a co-shipping template:
+[playbook-template.md](../../../../docs/governance/_templates/playbook-template.md),
+[task-detail.md](../../../../docs/governance/_templates/task-detail.md),
+[runbook-template.md](../../../../docs/governance/_templates/runbook-template.md),
+[post-mortem-template.md](../../../../docs/governance/_templates/post-mortem-template.md).
+Copy the template, then apply the craft here. The craft the templates *don't*
+carry: keep each section one altitude (a playbook sequences, it doesn't exhaust),
+and let the verification block name the exact commands that prove done.
+
+## Splitting vs sectioning
+
+Add a section to an existing doc when the topic shares the doc's scope. Create a
+new doc only when the scope genuinely differs *and* a reader would look for it
+separately. A 2000-line doc that covers six scopes is six docs; a six-line doc
+that duplicates a section of another is zero docs.

core/skills/technical-writing/references/writing-craft.md

@@ -0,0 +1,59 @@
+<!-- domain:DOCS | layer:reference | ssot:true | updated:2026-06-04 -->
+# Writing Craft — Sentences, Paragraphs, Structure
+
+> P: The sentence- and paragraph-level moves that make technical prose act-on-able the first read.
+> R: Drafting or editing any doc, README, ADR, or long comment.
+> S: Choosing which doc layer to write — see [doc-anatomy.md](doc-anatomy.md).
+> N: [SKILL.md](../SKILL.md), [doc-checklist.md](../assets/doc-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Structure — newspaper, not novel
+
+Lead with the conclusion; expand below. The reader who stops after the first paragraph should still have the answer. Detail descends: point → why → how → edge cases.
+
+```markdown
+# Wrong — buries the lede
+This document describes the various considerations that were taken into
+account when designing the caching layer, including several trade-offs...
+
+# Correct — point first
+Cache reads in Redis with a 60s TTL; writes invalidate the key. Below: why
+60s, and the two cases where you must bypass the cache.
+```
+
+## Sentences — active, present, specific
+
+| Weak | Strong |
+|---|---|
+| "The request may be rejected by the validator." | "The validator rejects the request when `amount` is negative." |
+| "Performance was improved." | "p95 latency dropped from 240 ms to 90 ms." |
+| "This should be handled appropriately." | "Retry twice with exponential backoff, then dead-letter." |
+| "There are several ways to do this." | "Three ways; use the first unless you need streaming." |
+
+Cut hedges (*may, might, could, generally, typically*) unless the uncertainty is the point. Cut intensifiers (*very, really, quite*). Name the subject — passive voice hides who acts.
+
+## Paragraphs — one idea, front-loaded
+
+First sentence states the idea; the rest supports it. If you can't summarize a paragraph in its first sentence, it holds two ideas — split it. Three sentences that each say the same thing collapse to one.
+
+## Lists vs prose vs tables
+
+- **Prose** — reasoning, a "why", a narrative the reader follows once.
+- **List** — steps in order, or a set of peers (≤7; past that, a table).
+- **Table** — comparisons across a fixed set of dimensions. If every row repeats a column, that column is prose.
+
+## Specificity checklist
+
+- Every "fast / slow / large / small" → a number or it's deleted.
+- Every "the file / the function / the config" → a path or symbol.
+- Every "should" → either "must" (a rule) or "consider" (a suggestion) — pick.
+- Every claim about behaviour → traceable to a file, a test, or a measurement.
+
+## Editing pass (do this before shipping)
+
+1. Delete the first sentence if it's preamble ("This section covers…").
+2. Read each heading in order — do they tell the story alone? If not, rename.
+3. Find every hedge/intensifier — justify or cut.
+4. Find every vague noun — replace with the path/symbol.
+5. Find every code-adjacent claim — verify against the code, not memory.

core/skills/technical-writing/scripts/new_doc.py

@@ -0,0 +1,81 @@
+"""Scaffold a docs/ markdown file with the canonical coding-os header.
+
+PURPOSE:      Emit a doc that already carries the machine-readable header +
+              Purpose/Read-when/Skip-when/Read-next + Nav, so regen_doc_index
+              indexes it and the renderer finds it. Writer fills the body.
+INPUT:        --layer <index|playbook|spec|policy|reference|adr|task> (required)
+              --domain <BACKEND|FRONTEND|DOCS|INFRA|META|...> (required)
+              --title  "<human title>" (required)
+              [--root docs/<dir>]  target dir (default: docs)
+              [--ssot true|false]  default true
+              [--date YYYY-MM-DD]  header date (default: today, UTC)
+              [--force]
+OUTPUT:       <root>/<slug>.md. Prints the path on stdout.
+DEPENDENCIES: stdlib only.
+NOTES:        Idempotent (refuses overwrite without --force). Layer is
+              validated against docs-system.md's taxonomy. Spec:
+              docs/playbooks/skill-authoring.md + docs/governance/docs-system.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+LAYERS = ("index", "playbook", "spec", "policy", "reference", "adr", "task")
+
+
+def slugify(title: str) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
+    return s or "untitled"
+
+
+def render(layer: str, domain: str, title: str, ssot: str, date: str) -> str:
+    return (
+        f"<!-- domain:{domain} | layer:{layer} | ssot:{ssot} | updated:{date} -->\n"
+        f"# {title}\n\n"
+        "Purpose: <one line — what this doc is for>.\n"
+        "Read when: <the trigger situation>.\n"
+        "Skip when: <when another doc is the right one>.\n"
+        "Read next: <[related](related.md)>\n\n"
+        "> Nav: [Section Index](./00-index.md) | [Docs Index](../00-index.md)\n\n"
+        "## <First section — one idea>\n\n"
+        "<body>\n"
+    )
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--layer", required=True, choices=LAYERS)
+    parser.add_argument("--domain", required=True)
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--root", default="docs", type=Path)
+    parser.add_argument("--ssot", default="true", choices=("true", "false"))
+    parser.add_argument("--date", default=None)
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args(argv)
+
+    date = args.date or datetime.now(timezone.utc).date().isoformat()
+    if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", date):
+        print(f"error: --date must be YYYY-MM-DD, got {date!r}", file=sys.stderr)
+        return 2
+
+    args.root.mkdir(parents=True, exist_ok=True)
+    target = args.root / f"{slugify(args.title)}.md"
+    if target.exists() and not args.force:
+        print(f"error: {target} exists (use --force)", file=sys.stderr)
+        return 1
+
+    target.write_text(
+        render(args.layer, args.domain.upper(), args.title, args.ssot, date),
+        encoding="utf-8",
+    )
+    print(str(target))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/terraform-k8s/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: terraform-k8s
+description: Author and operate infrastructure-as-code with Terraform/OpenTofu and Kubernetes manifests — declarative provisioning, state management, modules, plan/apply discipline, and the K8s object model (Deployment/Service/Ingress, probes, requests/limits, HPA, ConfigMap/Secret, RBAC). Use when writing a Terraform module, structuring remote state and workspaces, debugging drift or a destructive plan, writing or reviewing K8s YAML/Helm/Kustomize, sizing requests/limits, or wiring probes. Boundary vs deployment-cicd — deployment-cicd owns the release process (CI pipeline, build/test stages, blue-green/canary/rolling rollout, version tagging, rollback playbook); this skill owns the substrate those releases deploy onto — declarative provisioning of cloud resources and the Kubernetes object definitions themselves. The pipeline runs apply; this skill is what those files contain. Defers image-build craft to docker and host-level tuning to linux-sysadmin.
+tier: infra
+domain: [infra]
+last_reviewed: "2026-06-14"
+---
+
+# Terraform & Kubernetes — The Declarative Substrate
+
+A practical guide to provisioning cloud infrastructure with Terraform/OpenTofu and defining workloads as Kubernetes objects, such that the system state lives in version control and a fresh environment is one `apply` away. Stack-agnostic across cloud providers; recipes target AWS/GCP/Azure providers and vanilla K8s + Helm/Kustomize.
+
+## When to Use This Skill
+
+- Writing or reviewing a Terraform/OpenTofu module — inputs, outputs, resource graph.
+- Structuring remote state, workspaces/environments, and state locking before a team touches it.
+- Reading a `terraform plan` that wants to destroy/recreate something and deciding if that is safe.
+- Authoring K8s manifests (Deployment, Service, Ingress) or a Helm chart / Kustomize overlay.
+- Sizing resource requests/limits, wiring liveness/readiness/startup probes, configuring an HPA.
+- Managing config and secrets (ConfigMap, Secret, external secret operators) and RBAC.
+
+Skip when: the question is *how releases ship* (pipeline stages, rollout strategy, versioning, rollback) — that is deployment-cicd. This skill is the infrastructure those releases land on.
+
+## Terraform — State Is the Whole Game
+
+Terraform's model: a `.tf` description of desired state, a state file recording what actually exists, and `plan`/`apply` reconciling the two. Everything hard about Terraform is about state.
+
+- **Remote, locked state from day one.** Never a local `terraform.tfstate` for shared infra — two `apply`s race and corrupt it. Use an S3/GCS backend with DynamoDB/native locking. The state file contains secrets in plaintext → encrypt at rest, restrict access.
+- **`plan` before every `apply`, read every line.** Especially `-/+ destroy and then create`: that recreates a resource (new DB, new IP, downtime). A force-new on an attribute you thought was mutable is the classic 2 a.m. outage.
+- **Never edit the state file by hand.** Use `terraform state mv` / `import` / `rm`. Hand-editing JSON state desyncs it from reality.
+- **Pin provider and module versions.** `~> 5.0`, not unconstrained — an unpinned provider upgrades mid-`apply` and changes resource behavior under you.
+- **Drift is real.** Someone clicks in the console; `plan` now wants to "fix" it. Detect drift in CI (`plan` on a schedule, alert on non-empty diff); decide console-vs-code ownership per resource.
+
+### Module structure
+
+```hcl
+# A module: a reusable unit with a typed interface. Not a dumping ground.
+variable "environment" { type = string }
+variable "instance_count" {
+  type    = number
+  default = 2
+  validation {
+    condition     = var.instance_count >= 1
+    error_message = "instance_count must be at least 1."
+  }
+}
+output "service_endpoint" { value = aws_lb.this.dns_name }
+```
+
+- One module = one cohesive concern (a VPC, a service, a database). Compose, don't nest deeply.
+- Inputs typed and `validation`-guarded; outputs are the module's contract — downstream modules consume them, so treat output renames as breaking changes.
+- Separate environments by **workspace or directory + tfvars**, not by copy-pasting modules. The module is the same; the inputs differ.
+
+## Kubernetes — Declare the Desired State, Let the Controller Converge
+
+K8s is a control loop: declare objects, controllers drive actual state toward them. Author the objects correctly and the platform self-heals.
+
+### Deployment essentials — the four things people skip
+
+| Field | Why it is mandatory | What breaks without it |
+|---|---|---|
+| **resource `requests`** | scheduler placement + QoS class | pods land on overloaded nodes; no Guaranteed QoS |
+| **resource `limits`** | cap runaway containers | one container OOMs the node's neighbors |
+| **`readinessProbe`** | gate traffic until the pod can serve | requests hit a pod still booting → 502s during deploy |
+| **`livenessProbe`** | restart a wedged container | a deadlocked pod serves errors forever |
+
+```yaml
+resources:
+  requests: { cpu: "100m", memory: "128Mi" }   # scheduler reserves this
+  limits:   { cpu: "500m", memory: "256Mi" }   # hard cap; CPU throttles, memory OOM-kills
+readinessProbe:
+  httpGet: { path: /healthz, port: 8080 }
+  initialDelaySeconds: 5
+  periodSeconds: 10
+livenessProbe:
+  httpGet: { path: /livez, port: 8080 }
+  initialDelaySeconds: 15
+  periodSeconds: 20
+```
+
+- **Readiness ≠ liveness.** Readiness = "route traffic here?"; liveness = "kill and restart?". Conflating them (one `/health` doing both) causes restart storms when a dependency is briefly down — the pod should go *unready*, not get *killed*.
+- **Set `requests` even if unsure.** Without them the scheduler treats the pod as zero-cost and bin-packs until the node falls over. Requests too high waste capacity; missing entirely is worse.
+- **Memory limit hit = OOM-kill (hard); CPU limit hit = throttle (soft).** Size memory generously, CPU tightly.
+
+### Config, secrets, scaling, access
+
+- **ConfigMap** for non-secret config, **Secret** for credentials (base64 is *encoding*, not encryption — enable encryption-at-rest or an external secrets operator: External Secrets, Sealed Secrets, Vault).
+- **HorizontalPodAutoscaler** scales replicas on a metric (CPU/memory/custom). Pair with sane `requests` — the HPA computes utilization against the request.
+- **RBAC least-privilege.** Namespaced `Role` + `RoleBinding`, scoped ServiceAccounts. No `cluster-admin` for an app pod.
+- **Templating: Helm vs Kustomize.** Helm for packaged, parameterized, redistributable charts; Kustomize for overlay-per-environment on plain manifests. Don't run both on the same object — pick one per surface.
+
+## The Terraform ↔ K8s Seam
+
+A common split: Terraform provisions the *cluster and cloud resources* (VPC, managed K8s control plane, managed DB, IAM, DNS); K8s manifests define the *workloads inside it*. Provisioning the cluster with Terraform and the in-cluster objects with GitOps (Argo CD / Flux) is the mainstream 2026 pattern — Terraform for the substrate, GitOps for what runs on it. Avoid managing fast-churning in-cluster objects through Terraform's slow plan/apply loop.
+
+## Anti-Patterns (reject in review, fix on sight)
+
+- **Local/unlocked Terraform state** for shared infra — corruption on concurrent apply.
+- **Applying without reading the plan** — a silent destroy/recreate of a stateful resource.
+- **Hand-editing the state file** — use `state mv`/`import`/`rm`.
+- **Unpinned providers/modules** — non-reproducible builds, surprise behavior changes.
+- **K8s Deployments with no requests/limits** — the node-killer.
+- **One probe doing liveness + readiness** — restart storms on transient dependency blips.
+- **Secrets as plain ConfigMaps / committed to git** — base64 is not encryption.
+- **`:latest` image tags in manifests** — non-reproducible rollouts, broken rollback (defer image discipline to docker).
+- **`cluster-admin` for application workloads** — blast radius of a compromised pod is the whole cluster.
+- **Copy-pasted modules per environment** — drift between supposedly-identical envs; parameterize instead.
+
+## Tools per surface (2026 defaults)
+
+| Need | Default | Alternatives |
+|---|---|---|
+| IaC engine | OpenTofu / Terraform | Pulumi (general-purpose languages), CDK |
+| State backend | S3 + DynamoDB lock / GCS / Terraform Cloud | Spacelift, env0 |
+| K8s templating | Helm or Kustomize | jsonnet, cdk8s |
+| In-cluster GitOps delivery | Argo CD / Flux | (pairs with deployment-cicd) |
+| Policy / guardrails | OPA/Gatekeeper, Kyverno, `tflint`/`checkov` | Conftest |
+| Secrets in K8s | External Secrets Operator, Sealed Secrets, Vault | cloud-native secret store CSI |
+
+## Pairs With
+
+- **deployment-cicd** — owns the release *process* (pipeline, rollout strategy, versioning, rollback) that *invokes* `terraform apply` / `kubectl apply`; this skill is the content of those files.
+- **docker** — the image-build craft (multi-stage, minimal base, non-root) that produces what a K8s Deployment runs.
+- **linux-sysadmin** — host/node-level tuning beneath the cluster.
+- **observability** — `requests`/`limits` saturation, probe failures, and HPA decisions are golden signals; export them.
+- **security-web** — RBAC, secrets handling, and supply-chain (image provenance) as the security overlay.
+
+## See also
+
+- Terraform / OpenTofu docs — backends, state, modules, `import`.
+- Kubernetes docs — Configuration Best Practices; Pod resource management; probes.
+- *Kubernetes Patterns* (Ibryam & Huß) — health probe, predictable demands, declarative deployment patterns.
+- Argo CD / Flux docs — GitOps delivery into the cluster.