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).
This commit is contained in:
saravanakumardb1
parent
a55f207f80
commit
82cdebeb87
133
docs/devops/CODEX_DELEGATION_PROMPT.md
Normal file
133
docs/devops/CODEX_DELEGATION_PROMPT.md
Normal file
@ -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.
|
||||||
Loading…
Reference in New Issue
Block a user