Day-one Development¶
Internal product developers only
This page is for people who build Engineering Runtime (binary, hubs, docs, Control Plane). Customers and end users should use docs.engineeringruntime.com (Installation / Local Setup) instead.
Engineering Runtime is a multi-repo project. Day-one means: clone the map,
bootstrap local siblings, read the owning hub’s CLAUDE.md, then edit with
relative paths. Do not treat GitHub URLs as the day-to-day workflow.
Canonical project map (source of truth for layout):
engineering-runtime-workspace/CLAUDE.md.
Who owns what¶
| Surface | Hub | Typical work |
|---|---|---|
| Runtime binary, providers, engines, policy/audit | Product → engineering-runtime |
Go CLI / SSOT |
| Capabilities, samples, releases, AI agent, docs, series, this developer site | Product children | Supportive of the binary |
| Portal / app / shared API | Control Plane | Governance UI + api.engineeringruntime.com |
| ER map, bootstrap scripts, feature proposals | Workspace | Intake + day-one tooling |
| Raw thought-leadership drafts | Blogs | Drafts → polish into series |
Dependency model (product): engineering-runtime is the SSOT. Other
product children must not invent features the binary does not support. Extend
the binary first, then update supportive siblings in the same effort.
Control Plane is a separate hub. Runtime must keep working if Control Plane
is down. The only required product → Control Plane publish path is regenerating
the UI catalog via app-api deploy-cloud-run (workflow_dispatch).
1. Full ER tree (recommended)¶
mkdir -p ER && cd ER
git clone https://github.com/kishore-gutta/engineering-runtime-workspace.git
cd engineering-runtime-workspace
./scripts/bootstrap.sh
bootstrap.sh clones missing hubs and children (never overwrites existing
checkouts), then runs verify.sh. Fix any ✗ and re-run until you see
Ready for development.
Scripts lifecycle¶
| Script | When | What |
|---|---|---|
bootstrap.sh |
Day one (safe to re-run) | Clone missing hubs + children; then verify |
update.sh |
Daily | git pull --ff-only on every checkout (skips dirty trees); fill missing children; verify |
verify.sh |
Anytime | Clones + Go 1.23+ + Docker health |
clean.sh |
Optional | Remove local junk only — never deletes git repos |
Daily:
Expected layout¶
ER/
├── engineering-runtime-workspace/ ← map, scripts, proposals
├── engineering-runtime-product/
│ ├── engineering-runtime/ ← SSOT binary
│ ├── engineering-runtime-capabilities/
│ ├── engineering-runtime-samples/
│ ├── engineering-runtime-releases/
│ ├── engineering-runtime-development/
│ ├── engineering-runtime-ai-agent/
│ ├── engineering-runtime-docs/ ← docs.engineeringruntime.com (customers)
│ ├── engineering-runtime-developer/ ← this site (developers)
│ └── engineering-runtime-series/ ← engineeringruntime.com
├── engineering-runtime-control-plane/
│ ├── engineering-runtime-portal-ui/
│ ├── engineering-runtime-app-ui/
│ └── engineering-runtime-app-api/
└── engineering-runtime-blogs/
2. Open the right folder in Claude Code / Cursor¶
Read in this order before large edits:
engineering-runtime-workspace/CLAUDE.md— ER map- Owning hub
CLAUDE.md— product or Control Plane - Target child
CLAUDE.md— e.g.engineering-runtime/,app-api/
Practical tip: open the ER/ folder (or workspace + the hub you will edit)
so relative sibling links resolve.
3. Hub-only clones (optional)¶
Use these when you do not need the full tree.
Product hub only¶
git clone https://github.com/kishore-gutta/engineering-runtime-product.git
cd engineering-runtime-product
./scripts/clone-children.sh
Hub guide:
engineering-runtime-product/CLAUDE.md.
Control Plane hub only¶
Portal / app / API day-one does not require the product hub:
git clone https://github.com/kishore-gutta/engineering-runtime-control-plane.git
cd engineering-runtime-control-plane
./scripts/clone-children.sh
Hub guide:
engineering-runtime-control-plane/CLAUDE.md.
Binary-only (minimal)¶
git clone https://github.com/kishore-gutta/engineering-runtime.git
cd engineering-runtime
go build -o runtime .
./runtime version
Also see that repo’s LOCAL_SETUP.md and docs/05-development/local-setup.md.
4. Build and smoke-test the binary¶
See Local Development for build commands and a throwaway Runtime Home sandbox.
Requirements: Go 1.23+ (verify script reports this).
5. Local siblings (day-to-day rule)¶
Inside a hub, read and edit peers with relative paths (../engineering-runtime-docs/,
../engineering-runtime-portal-ui/, …). After workspace bootstrap, sibling hubs
under ER/ are local too.
GitHub / gh api is a rare fallback only when a peer checkout is missing —
prefer ./scripts/update.sh to clone it.
Children stay separate git remotes. Commit and push in each repo you touch.
Hooks may remind or edit local siblings; they must never git push another
repo’s remote.
6. New features — propose, approve, implement, close¶
Do not land new product or Control Plane features from workspace intake until a proposal is approved.
| Step | Who | Action |
|---|---|---|
| 1. Capture | anyone | Drop notes/screenshots in engineering-runtime-workspace/inbox/ (local-only; not committed) |
| 2. Propose | author / agent | Copy analyzed/proposals/_TEMPLATE.md → YYYY-MM-DD-short-slug.md. Set Status ready-for-review. Commit workspace. Stop. |
| 3. Approve | human reviewer | Same file: Status approved or rejected, Reviewer + date. Commit workspace. |
| 4. Implement | developer / agent | Re-read Status. Only if approved, edit the named Owner hub / Primary repos. Commit those repos. |
| 5. Close | developer / agent | Status → implemented. Clear related inbox/ files. Commit workspace. |
Status meanings:
| Status | May implement in product/CP? |
|---|---|
draft / ready-for-review / rejected |
No |
approved |
Yes — scope in that proposal only |
implemented |
No — already done |
Background notes (not a ticket queue):
analyzed/reading/.
Recipe + template:
Worked examples:
7. Same-effort updates (product hub)¶
When a change lands in the binary (or changes what it supports), update every relevant supportive sibling before you finish, for example:
| Change | Also update |
|---|---|
| New/changed provider or CLI | engineering-runtime-docs (+ PROGRESS.md) |
| New reusable capability | engineering-runtime-capabilities (+ sample if proving CI) |
| New term / architecture story | engineering-runtime-series (must not invent beyond the binary) |
| Hub / day-one developer process | engineering-runtime-developer (this site) |
| Release binary | engineering-runtime-releases + docs release notes |
Public sites:
| Site | Role |
|---|---|
| developer.engineeringruntime.com | This site — internal day-one / hubs |
| docs.engineeringruntime.com | Customer how-to — must match implemented surface |
| engineeringruntime.com | Why / architecture (series) — not hub clone instructions |
Hub entry links¶
| Repo | Role |
|---|---|
engineering-runtime-workspace |
ER map, scripts, proposals |
engineering-runtime-product |
Product hub |
engineering-runtime-control-plane |
Control Plane hub |
engineering-runtime |
SSOT binary |
engineering-runtime-developer |
This site |
engineering-runtime-blogs |
Draft posts |
Next for customers (not this site)¶
| Goal | Page |
|---|---|
| Install the release binary | Installation |
| First governed operation | Quick Start |
| Laptop day-to-day use | Local Setup |