diff --git a/CHANGELOG.md b/CHANGELOG.md index 526ec3b..7cbff4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ Please choose versions by [Semantic Versioning](http://semver.org/). * MINOR version when you add functionality in a backwards-compatible manner, and * PATCH version when you make backwards-compatible bug fixes. +## Unreleased + +- launch-agent: default new agents to stateless LLM token auth (Agent Design Guide §7.2c) instead of the OAuth-PVC shape; interview Part 2 runtime tier + Part 7 security now cover GitHub App naming (§7.2a) and per-stage App pairs; config-crd-template demotes the PVC to an opt-in exception + ## v0.77.2 - Bump `golang.org/x/text` to v0.39.0 (CVE-2026-56852) diff --git a/skills/launch-agent/SKILL.md b/skills/launch-agent/SKILL.md index 373431f..666d313 100644 --- a/skills/launch-agent/SKILL.md +++ b/skills/launch-agent/SKILL.md @@ -276,7 +276,7 @@ In all cases, report the failing precommit output verbatim in the halt message s - `references/shapes.md` — shape decision matrix - `references/interview.md` — 45-Q script - `references/{config-crd,vault-page,goal,scenario,next-directions}-template.{yaml,md}` — output templates -- [[Agent Design Guide]] — full 45-Q checklist (source of truth) +- [[Agent Design Guide]] — full 45-Q checklist (source of truth); esp. its § 7.2 auth conventions, sections **"GitHub App auth — one App per component, per stage"** (naming `Ben's ` / `Ben's Dev`, per-stage least-privilege) + **"LLM auth — fleet norm is stateless token, NOT OAuth PVC"** (stateless `ANTHROPIC_AUTH_TOKEN` Secret) — the two conventions the scaffold defaults must honor (referenced by section title, not number, so a guide reorg is detectable) - [[Quick-Launch New Agents]] — parent goal - [[Claude Managed Agents - Ideas for bborbe Framework]] — architectural rationale + interview-first pattern - `anthropics/launch-your-agent` — Anthropic's analogous skill (different runtime, same shape) diff --git a/skills/launch-agent/references/config-crd-template.yaml b/skills/launch-agent/references/config-crd-template.yaml index 7a815ca..9557663 100644 --- a/skills/launch-agent/references/config-crd-template.yaml +++ b/skills/launch-agent/references/config-crd-template.yaml @@ -28,12 +28,28 @@ spec: env: ALLOWED_TOOLS: "" # e.g. "Bash,Read,Edit,Grep" LOGLEVEL: "2" + # LLM auth — FLEET DEFAULT is stateless token, NOT an OAuth PVC. + # Per [[Agent Design Guide]] §7.2c: every running Claude-based agent authenticates + # via ANTHROPIC_AUTH_TOKEN in its Secret + these two plain env vars. Keep this block + # unless you deliberately chose the Max-subscription OAuth-PVC exception below. + ANTHROPIC_BASE_URL: https://api.minimax.io/anthropic # MiniMax default; swap for your provider + ANTHROPIC_MODEL: MiniMax-M2.7-highspeed # Domain-specific env vars from interview Part 5 (Inputs): # : "" - # k8s Secret containing teamvault-resolved creds (from interview Part 7.3) - secretName: # see k8s/-secret.yaml for the teamvault references + # k8s Secret containing teamvault-resolved creds (from interview Part 7.3). + # Includes ANTHROPIC_AUTH_TOKEN (the LLM token, §7.2c) + SENTRY_DSN + any domain creds. + # See k8s/-secret.yaml for the teamvault references. + secretName: - # PVC for persistent per-agent state (Claude OAuth, memory, etc.). Omit if stateless. - volumeClaim: # e.g. -claude-oauth; remove block if none - volumeMountPath: /home/claude/.claude + # ── OAuth PVC (OPT-IN EXCEPTION — most agents do NOT need this) ────────────── + # Only if you chose the Max-subscription OAuth tier in the interview (Part 2 runtime + # tier). It buys flat-rate usage but costs: interactive `claude login` seeding per + # namespace, the Agent - Refresh Claude OAuth Login runbook, an oauth-probe task type, + # and local-path PVC node-pinning. Stateless token auth (the env block above) needs + # NO volume — for the default case, leave the block below entirely commented out. + # + # To enable: uncomment BOTH lines together (a volumeClaim without volumeMountPath, or + # vice-versa, is invalid and the Config CR is silently rejected): + # volumeClaim: -claude-oauth + # volumeMountPath: /home/claude/.claude diff --git a/skills/launch-agent/references/interview.md b/skills/launch-agent/references/interview.md index 96287e3..717bf4a 100644 --- a/skills/launch-agent/references/interview.md +++ b/skills/launch-agent/references/interview.md @@ -18,11 +18,11 @@ Conversational walk through the [[Agent Design Guide]]'s 8 parts. Use `AskUserQu 1. **Role** (open): What does the agent do? (short kebab-able label, e.g. `dark-factory`, `pr-review`) 2. **Repo name** (suggest-with-override, per SKILL.md § naming): normalize the role to a slug, strip any trailing `-agent`, **suggest** `-agent`, and let the user overwrite with any valid repo name (e.g. `github-dark-factory-agent` — `github-` repo prefix is valid). The chosen value is `` = `bborbe/`. No forced `agent-` prefix, no double `-agent`. 3. **Purpose statement** (open): 1-2 sentence purpose for the README and Config CRD description. -4. **Runtime tier** (`AskUserQuestion`): Which provider/cost tier? - - Anthropic Max subscription (Claude Code, included quota) - - Sonnet API (pay-per-token) - - Local Qwen (on-cluster, no external API) - - MiniMax (cheap, Tier-D quality) +4. **Runtime tier** (`AskUserQuestion`): Which provider/cost tier? **Default = MiniMax** (the fleet standard — stateless token auth, no PVC; see §7.2c). All non-Max tiers render the stateless `ANTHROPIC_AUTH_TOKEN` Secret + `ANTHROPIC_BASE_URL`/`ANTHROPIC_MODEL` env block. Only the Max tier adds the OAuth-PVC exception (interactive `claude login` seeding + refresh runbook + oauth-probe — flag this cost when the user picks it). + - MiniMax (cheap, Tier-D quality) — **recommended default; stateless token** + - Sonnet API (pay-per-token) — stateless token, stronger judgment/repair + - Local Qwen (on-cluster, no external API) — stateless token + - Anthropic Max subscription (Claude Code, included quota) — **OAuth-PVC exception**; adds seeding + runbook + probe overhead 5. **Domain & repo** (silent): `bborbe/` (the chosen basename); document where the new repo lives. → Confirm: "Captured: on . Proceed?" @@ -91,7 +91,8 @@ Conversational walk through the [[Agent Design Guide]]'s 8 parts. Use `AskUserQu - Yes, for writes only (read-only autonomous, write gated) - Yes, for all actions (advisory only, never executes) 2. **Error handling per class** (open): for each failure mode (transient infra, semantic error, rate limit, missing dependency), what's the response? -3. **Security boundaries** (open): what secrets does the agent need? (teamvault keys, OAuth tokens) — list the teamvault key names (NOT raw secrets). +3. **Security boundaries** (open): what secrets does the agent need? (teamvault keys — list key names, NOT raw secrets). Render the Secret per [[Agent Design Guide]] §7.2c: `ANTHROPIC_AUTH_TOKEN` (inline TeamVault ID `MOPmQL` for the shared MiniMax token — inline because it's the same across stages) + `SENTRY_DSN` + any domain creds. Use env-indirection (`{{ "MY_KEY" | env | ... }}` + `dev.env`/`prod.env`) ONLY for IDs that differ per stage. + - **If the agent touches GitHub** (`AskUserQuestion` — GitHub-integrating?): it authenticates as a **GitHub App, never a PAT** (§7.2a). Create a per-stage App PAIR now: prod = `Ben's `, dev = `Ben's Dev` (plain ` Dev` suffix, NOT `[Dev]`). Least-privilege per the §7.2a permission table (watcher = read-only; agent that pushes = Contents R/W + PR R/W, no Workflows). Capture per App: App ID + Installation ID (public — go in CR env), PEM → TeamVault (per-stage ID → env-indirection in the Secret). Note the App pair in NEXT-DIRECTIONS so the deploy checklist reminds the operator to install dev→canary / prod→bborbe/*. 4. **Assumptions** (open): what does the agent assume about its environment that must remain true? (Kafka topic exists, vault is mounted RW, git-rest is reachable, etc.) 5. **Data privacy** (open): does the agent read/write any PII or sensitive data? If yes, where does it land?