From 222b8feca3a579effe215044289742fbc77f8008 Mon Sep 17 00:00:00 2001 From: davekilleen Date: Thu, 6 Aug 2026 08:03:54 +0000 Subject: [PATCH 1/2] docs(agents): add GitHub runner preflight guidance --- AGENTS.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 313ccc57..850a4491 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,55 @@ product persona — the root `CLAUDE.md` is seed prose shipped into user vaults ("You are Dex…"); it is a product surface, not contributor guidance. Edit it like UI copy, not like docs. +## Communicating with Dave + +Dave is a non-technical founder. Lead with the outcome and explain what is +happening in plain language; briefly explain an unavoidable technical term the +first time it appears. + +- Use an ADHD-friendly structure: keep steps short and numbered, make the one + required action unmistakable, and prefer copy-paste prompts or commands. +- When Dave must act, begin with a **What I need from you** block stating the + exact action, where to do it, why Dave is needed, and what will happen next. +- When blocked, state the exact blocker, what is and is not affected, the + lowest-lift recovery action, and how to prevent the issue recurring. +- Never ask Dave to diagnose Git, mounts, permissions, credentials, or similar + mechanics, and never ask him to paste secrets into chat. +- Never claim something is fixed, committed, pushed, merged, published, or live + without verifying the result Dave will actually experience. + +## GitHub access in managed Codex runners + +The normal Devbox terminal and a managed Codex runner are separate execution +contexts. A successful GitHub check in one does not prove that the other has +working DNS or credentials. Before any GitHub fetch, push, or remote inspection +from a managed runner, run these read-only checks in that same runner: + +```bash +getent hosts github.com +gh auth status --hostname github.com +gh api user --hostname github.com --jq '"GITHUB_OK: @" + .login' +git ls-remote origin HEAD +``` + +If a check fails, classify the failure precisely: + +- **Managed-runner DNS**: `getent hosts github.com` cannot resolve the name. +- **Managed-runner HTTPS credentials**: DNS works but `gh api` or HTTPS Git + authentication fails. +- **SSH key or route**: the repository uses SSH and the SSH remote fails. + +Do not collapse these into “Devbox cannot access GitHub.” Do not ask Dave to +re-authenticate or paste a token when his normal Devbox check already passes. +Continue safe local work where possible, and use the already-authenticated +Devbox terminal as the fallback for a remote GitHub operation. + +If the remedy requires runner bootstrap, host service, DNS, credential-mount, +or deployment-key changes, do not edit `/etc/resolv.conf` as a temporary fix, +copy secrets, or claim the issue is fixed. Report the exact layer, the exact +configuration change required, and the verification command; ask for approval +only when a host or credential change genuinely needs it. + ## Orient before you touch anything 1. Run `/dex-orient` (or `python3 scripts/dex_state.py --digest`) — released From 0dede3a5137cb0b0591300f08168eaa4309d7e47 Mon Sep 17 00:00:00 2001 From: davekilleen Date: Thu, 6 Aug 2026 13:25:30 +0000 Subject: [PATCH 2/2] docs(agents): avoid personal founder wording --- AGENTS.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 850a4491..0572f192 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,22 +5,23 @@ product persona — the root `CLAUDE.md` is seed prose shipped into user vaults ("You are Dex…"); it is a product surface, not contributor guidance. Edit it like UI copy, not like docs. -## Communicating with Dave +## Communicating with the founder -Dave is a non-technical founder. Lead with the outcome and explain what is +The founder is non-technical. Lead with the outcome and explain what is happening in plain language; briefly explain an unavoidable technical term the first time it appears. - Use an ADHD-friendly structure: keep steps short and numbered, make the one required action unmistakable, and prefer copy-paste prompts or commands. -- When Dave must act, begin with a **What I need from you** block stating the - exact action, where to do it, why Dave is needed, and what will happen next. +- When the founder must act, begin with a **What I need from you** block stating + the exact action, where to do it, why the founder is needed, and what will + happen next. - When blocked, state the exact blocker, what is and is not affected, the lowest-lift recovery action, and how to prevent the issue recurring. -- Never ask Dave to diagnose Git, mounts, permissions, credentials, or similar - mechanics, and never ask him to paste secrets into chat. +- Never ask the founder to diagnose Git, mounts, permissions, credentials, or + similar mechanics, and never ask for secrets to be pasted into chat. - Never claim something is fixed, committed, pushed, merged, published, or live - without verifying the result Dave will actually experience. + without verifying the result the user will actually experience. ## GitHub access in managed Codex runners @@ -43,7 +44,7 @@ If a check fails, classify the failure precisely: authentication fails. - **SSH key or route**: the repository uses SSH and the SSH remote fails. -Do not collapse these into “Devbox cannot access GitHub.” Do not ask Dave to +Do not collapse these into “Devbox cannot access GitHub.” Do not ask the founder to re-authenticate or paste a token when his normal Devbox check already passes. Continue safe local work where possible, and use the already-authenticated Devbox terminal as the fallback for a remote GitHub operation.