From 82cdebeb8758ea81e72d7a8901f80f7d17f56ce6 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sun, 24 May 2026 18:26:50 -0700 Subject: [PATCH] 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). --- docs/devops/CODEX_DELEGATION_PROMPT.md | 133 +++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 docs/devops/CODEX_DELEGATION_PROMPT.md diff --git a/docs/devops/CODEX_DELEGATION_PROMPT.md b/docs/devops/CODEX_DELEGATION_PROMPT.md new file mode 100644 index 00000000..ab917f06 --- /dev/null +++ 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. complete — + - 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: + ` 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 ." + +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. 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.. The roadmap state is current as of commit ``." + +The checkbox state IS the resume pointer — no other state file needed.