docs(devops): add Codex delegation prompt + one-liner handoff

Captures the exact bootstrap prompt to paste to Codex on the Hostinger VM, plus a one-liner that just points Codex at the prompt file (after Codex has the repo). Also documents how to monitor Codex's progress from Cascade side (grep roadmap-update commits) and how to recover if it gets stuck (the checkbox state in the roadmap IS the resume pointer).
2026-05-24 18:26:50 -07:00 · 2026-05-24 18:26:50 -07:00 · 82cdebeb87
commit 82cdebeb87
parent a55f207f80
1 changed files with 133 additions and 0 deletions
--- a/docs/devops/CODEX_DELEGATION_PROMPT.md
+++ b/docs/devops/CODEX_DELEGATION_PROMPT.md
@ -0,0 +1,133 @@
+# Codex Delegation Prompt — Hostinger Gitea Runner Setup
+
+> Copy-paste the block below to Codex running on the Hostinger VM. It bootstraps Codex into reading and executing the master roadmap.
+
+---
+
+## The prompt
+
+```
+You are executing a multi-phase infrastructure setup on the Hostinger VM
+you're running on. Read and follow the master roadmap exactly.
+
+REPO: learning_ai_common_plat
+  Find it: `find ~ -maxdepth 4 -type d -name "learning_ai_common_plat" 2>/dev/null | head -3`
+
+ROADMAP: docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md
+
+INSTRUCTIONS:
+
+1. Read the roadmap top-to-bottom BEFORE starting any work. It points to
+   two companion docs (HOSTINGER_GITEA_ACT_RUNNER_SETUP.md and
+   GITEA_PACKAGES_PUBLISH_WORKFLOW.md) for implementation detail —
+   read those too.
+
+2. Execute phases P0 → P5 in order. Do NOT skip phases.
+
+3. After completing each numbered task (P0.1, P0.2, P1.1, ...), update
+   the roadmap file:
+   - Change `- [ ]` to `- [x]` for that task
+   - Fill in the `Commit:` field with the 7-char short SHA of the
+     commit that performed the actual work (NOT the roadmap-update
+     commit). For pure system changes (e.g., useradd), write
+     "_system change_".
+   - Fill in the `Status:` field with a one-line description of what
+     you observed.
+   - Commit the roadmap update with message:
+       chore(roadmap): mark P<phase>.<task> complete — <short note>
+   - Push to both remotes:
+       git push origin main && git push gitea main
+
+4. STOP and ask the human if ANY of these occur:
+   - A pre-flight check (P0) fails or surprises you
+   - The cross-Gitea SHA1 comparison (P3.6 or P5.4) does NOT match —
+     this is the load-bearing architectural invariant; do not paper
+     over it
+   - The runner registration token doesn't work or expires before you
+     can use it
+   - A step in a companion doc doesn't work as written (note in
+     "Surprises / deviations" and proceed only if safe)
+   - You need to deviate non-trivially from any companion doc
+   - The human's pre-execution answers (P0.3, P0.4) turn out to be
+     wrong (e.g., they said instance-level scope but you only have
+     repo admin)
+
+5. NEVER:
+   - Skip P3.6 or P5.4 (cross-Gitea SHA verification)
+   - Publish packages outside the workflow you just built
+   - Leave the throwaway @bytelyst/_runner-e2e-test package in either
+     Gitea registry after E2E
+   - Force-push the roadmap file
+   - Mark `[x]` if a task didn't fully succeed (use `[ ] FAILED:
+     <reason>` and stop)
+   - Run the runner daemon as root
+
+6. When P0–P5 are all `[x]`:
+   - Fill in the §"Final report" section of the roadmap with NO
+     placeholder strings left
+   - Mark P6.1 and P6.2 as `[x]`
+   - Push the final commit
+   - Reply back with: "Roadmap complete. P6.1 + P6.2 ticked. Awaiting
+     human review (R1–R9) on commit <sha>."
+
+PRE-EXECUTION QUESTIONS — ASK THE HUMAN BEFORE STARTING IF UNCLEAR:
+
+  a. What user owns `~/.gitea_npm_token` on this VM? (P0 pre-flight
+     check #10 in the runner setup doc will discover this; confirm
+     with the human.)
+  b. Confirm registration scope: instance-level (recommended). If the
+     human prefers org-level or repo-level, get that direction.
+  c. Confirm consent for the E2E throwaway package
+     (@bytelyst/_runner-e2e-test, published + deleted as part of P3).
+  d. For P5.1, ask which package to bump for the first real release.
+     Suggest a low-risk one (@bytelyst/errors or similar with stable
+     downstream consumers).
+  e. If `gh` CLI on this VM is not auth'd as saravanakumardb1 (the
+     Gitea/GitHub user), ask how to obtain a Gitea admin token for
+     the runner registration step (P1.3).
+
+START WITH P0. Read the roadmap. Then go.
+```
+
+---
+
+## One-liner handoff (paste this single line to Codex)
+
+```
+Read docs/devops/CODEX_DELEGATION_PROMPT.md in learning_ai_common_plat, then execute the prompt within. Begin with P0.
+```
+
+Or, if Codex doesn't have the repo yet:
+
+```
+Clone https://github.com/saravanakumardb1/learning_ai_common_plat (or whichever remote you can reach), open docs/devops/CODEX_DELEGATION_PROMPT.md, and execute the prompt within. Begin with P0.
+```
+
+---
+
+## Monitoring from your end (Cascade / corp Mac side)
+
+While Codex works, watch its progress commits flow into `learning_ai_common_plat/main`:
+
+```bash
+cd ~/code/mygh/learning_ai_common_plat
+git fetch origin
+git log --oneline --grep="chore(roadmap)" origin/main | head -30
+```
+
+Each `chore(roadmap): mark P<x>.<y> complete` commit = one checkbox ticked. When you see `chore(roadmap): mark P6.2 complete`, run the human review (R1–R9 in the roadmap doc).
+
+---
+
+## If Codex gets stuck
+
+It should stop and surface the question itself. If it doesn't, you can:
+
+1. Check the latest roadmap state on `origin/main`:
+   ```bash
+   git fetch origin && git show origin/main:docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md | grep -E "^\- \[" | head -30
+   ```
+2. Find the lowest unchecked `[ ]`.
+3. Tell Codex: "Resume from P<x>.<y>. The roadmap state is current as of commit `<sha>`."
+
+The checkbox state IS the resume pointer — no other state file needed.