Engineering Standardization Recommendation
- Prepared for: COO → incoming Product Owner
- Prepared by: Platform Engineering (Kent Gray)
- Date: 2026-07-17
- Status: Draft for ratification
How to read this package. This document is the executive layer: the situation, the recommendation, the decisions you need to make, and the rollout. The eight detailed standards live as chapters in
sections/and are referenced throughout. A one-page version for forwarding is in Executive Brief.
1. Executive Summary
Wasteology is adding developers and weighing two large platform consolidations — GCP → Azure and GitHub → Azure DevOps — at the same moment it has no written standard for how software is built, tracked, documented, or secured. The risk is not that we lack capability; it is that our capability is undocumented, unenforced, and concentrated in one person's head.
The central finding of this review is therefore counter-intuitive and good news: most of what a mature engineering org needs already exists at Wasteology and works. We already run a single Azure DevOps organization, a working uv/ruff/pytest toolchain, an auto-deploying documentation site, a code-grounded knowledge graph (lat.md) validated in CI, a library of reusable AI agents, an overnight agent-driven development pipeline, and — as of this week — a company-wide Azure access-and-cost governance standard. What is missing is the connective tissue: a declared standard, a template that makes the standard the path of least resistance, and an owner other than the founder-engineer.
This recommendation does three things:
- Elevates the scattered, already-working practices into one declared company standard a new hire (or contractor) can follow on day one.
- Fills the real gaps — a repo template, a thin everyday CLI, a documentation decision-rule, a contractor-onboarding runbook, and formal access/ABS request processes.
- Frames the two migrations as decisions, not foregone conclusions — with go/no-go criteria and, only if "go," a phased plan.
Posture: opinionated defaults grounded in what already works, each with an explicit PO decision point so the incoming owner can adopt-and-adjust rather than inherit a black box. Nothing here requires a rewrite; the dominant cost is documentation, enforcement, and one round of migrations — not new construction.
2. The Moment — Current-State Assessment
| Dimension | Where we are today | Consequence |
|---|---|---|
| Team | Several developers just onboarded; more coming | No repeatable onboarding → days lost per hire, inconsistent setups |
| Source control | Core repos on ADO; mars/Orbit, prefect-azure-infra, dbt warehouse still on GitHub | Two SCMs, two access planes, two audit logs for a small team |
| Cloud | Azure is the active platform; a GCP invoice/OCR stack (Trashy/BINS) runs in parallel | Split-cloud ops burden; GCP knowledge is largely orphaned (built by a contractor) |
| Project tracking | Ad-hoc; ADW auto-creates work items but humans don't consistently link commits | Work is invisible to anyone but the author |
| Repo creation | Manual; each repo hand-copies scaffolding | New repos silently miss steps |
| Documentation | Three surfaces (ADO Wiki, docs site, lat.md) with no rule for which to use | Design intent lands in chat; published docs rot |
| Agentic tooling | Rich and real, but no shared "when to use what" | Reinvention; capability locked to those who already know it |
| Access & resources | Just standardized (cloud-governance), but approval concentrated in one person | Key-person risk on every grant and every review |
| Contractors | Engaged (Korza, Mars/Orbit) but onboarded bespoke each time | Inconsistent security posture; IP/handoff risk |
The through-line risk is key-person concentration. Almost every standard below currently resolves to "kgray does it / knows it." The single highest-leverage outcome of ratifying this document is distributing that knowledge and authority to the incoming PO and the growing team.
3. Guiding Principles
These principles resolve the recurring trade-offs across all eight domains. When a specific rule is ambiguous, fall back to these.
- Standardize by elevating what works, not by importing what's fashionable. Every standard here is already running somewhere in the portfolio.
- Make the standard the path of least resistance. A repo template and a thin CLI mean "the right way" is also "the easy way." Standards that rely on discipline alone decay.
- Consolidate the surface area. One cloud, one SCM, one identity plane, one docs pipeline — each duplication is a permanent tax that a three-to-eight-person team cannot afford.
- Least privilege by default, escalate on need. New humans and contractors start read-only on dev; nothing prod on day one.
- Docs and design intent are code-grounded and mechanically validated (
lat.md+lat check), and published docs auto-sync from code — humans don't hand-maintain what a pipeline can. - Agentic-first, human-verified. Prefer skills/agents/ADW for repeatable work; never let an agent claim "done" without verification evidence; keep a human in the loop for anything irreversible.
- Decisions are recorded, not remembered. Migration verdicts and access grants become ADRs and git history, not tribal knowledge.
4. The Eight Standards at a Glance
Each row links to its detailed chapter. The "headline recommendation" is the opinionated default; the "top decision for the PO" is the single most consequential choice in that domain.
| # | Domain | Headline recommendation | Top decision for the PO | Chapter |
|---|---|---|---|---|
| A | ADO foundation, repo templating, branching, Boards | Single ADO org/project + area paths; seed every repo from a wg-template repo; trunk-based dev with squash-only PRs and branch policies; link work↔code with AB#<id> + auto-transition | Enforce wg-template as an ADO repository template? Sprints vs. Kanban? | A |
| B | Dev environment, dependency mgmt, thin CLI | uv + ruff + pytest, Python 3.12 pinned, uv.lock committed, uv sync --frozen in CI; ship a thin wg CLI (11 commands) via an ADO Artifacts feed for everyday users | Create the wasteology-feed now? Name + build sequence for the thin CLI? | B |
| C | Documentation (Wiki vs docs site vs lat.md) | Three surfaces, one job each: lat.md = design intent (code-validated), docs site = human-facing published docs (auto-synced), ADO Wiki = non-code process/notes/ADRs | Keep ADO Wiki strictly non-code, or allow product roadmaps there? | C |
| D | Agentic workflows + wg-agent-infra | A "when to use what" ladder (interactive → skill → global agent → ADW → multi-agent); wg-agent-infra is the one home for shared agents; a 3-stage prototype→global→autonomous promotion path; mandatory verification + secrets guardrails | Require human spec-review before ADW dispatch for customer-facing data? | D |
| E | Access governance + ABS requests | Two-layer model (RBAC + DB roles); read/write/admin tiers; least-privilege day-one onboarding checklist; sanctioned tooling (ops db, UAA-approved RBAC); a formal ABS request template for tenant/sub-level needs | Grant the incoming PO Reader on all 3 subs so reviews aren't advisory-only? | E |
| F | Third-party contractor onboarding | A 6-phase lifecycle; code in our ADO from day one; isolated daily-refreshed sandbox DB (the Korza model); Entra B2B time-boxed guests; a required documentation set (NDA/DPA/security questionnaire/handoff runbook); defined comms cadence + offboarding | Approve the standard contractor requirements as contract-mandatory defaults? | F |
| G | Migration frameworks + roadmap + PO 90-day plan | GCP→Azure = decide via go/no-go (gated on a 30-day bill + Document AI PoC); GitHub→ADO = recommend go, migrate mars after its Aug-15 go-live; a 7-phase unified rollout | Ratify the roadmap; set the two migration decision dates | G |
| H | API development & testing | Standardize on Bruno — git-native .bru collections in each API's repo, free/offline, bru run contract checks in CI; migrate the existing Postman collections via the bundled converter | Blocking vs. advisory CI contract checks to start? | H |
5. Consolidated PO Decision Register
Every "PO decision point" across the eight chapters, in one place, with the recommended default. This is the PO's ratification checklist — accept the default or amend, then record the verdict.
| # | Decision | Recommended default | Chapter |
|---|---|---|---|
| 1 | ADO structure | Single org/project + area paths (no new ADO projects) | A.1 |
| 2 | Repo template enforcement | Mark wg-template as an ADO template and keep the curl automation path | A.2 |
| 3 | Required PR reviewers on main | 1 default; 2 for repos that deploy straight to prod (palantiri, mars) | A.3 |
| 4 | Work cadence | Kanban (lower overhead, suits async ADW) over formal sprints | A.5 |
| 5 | Python version | 3.12 pinned; 90-day exception window for any 3.11 hold-outs | B1 |
| 6 | Internal package feed | Create wasteology-feed now (stable URL for templates + thin CLI) | B2 |
| 7 | Thin CLI name + scope | wg (pending WireGuard collision check); build status/standup/check/upgrade first | B3 |
| 8 | ADO Wiki scope | Keep it strictly non-code; use ADO Boards (not wiki) for roadmaps | C |
| 9 | Session-wrap requirement | Require /session-wrap for any session that committed code | D.1 |
| 10 | ADW dispatch gating | Auto-dispatch chores/low-risk; human spec review for billing/CRM/customer-facing | D.4 |
| 11 | Agent setup in provisioning | Automate wg-agent-infra linking in the day-one setup script | D.8 |
| 12 | New-developer default tier | Read-tier on dev, fast-path to dev-write; nothing prod on day one | E.2 |
| 13 | PO Azure access | Grant the PO Reader on all 3 subscriptions so access reviews are real, not advisory | E.6 |
| 14 | Second approver | Elevate a second person (e.g. tlewis) as DB-mutation co-approver / RG-scoped UAA to reduce key-person risk | E.1 |
| 15 | ABS requests | Track via a lightweight ADO Task tagged access-request for PO visibility | E.5 |
| 16 | Contractor requirements | Adopt the §F requirements as contract-mandatory defaults; simplify only items 6 & 10 for small engagements | F.2 |
| 17 | GitHub → ADO | Go. Migrate prefect-infra + dbt now; mars after Aug-15 go-live. Record in adr-002 by Day 30 | G2 |
| 18 | GCP → Azure | Decide by Day ~45, gated on the 30-day bill + Document AI PoC. Record in adr-001 | G1 |
| 19 | API-testing tool | Bruno — git-native .bru collections in-repo, bru run in CI; migrate the two existing Postman collections via the bundled converter | H.2 |
6. Rollout Roadmap (summary)
The full phase table, cross-phase dependencies, and week-by-week 30/60/90 plan are in Chapter G. In brief:
| Phase | Focus | Window |
|---|---|---|
| 0 | Foundation & ratification (approve standards, create template + feed, sign the RACI) | Days 1–30 |
| 1 | Dev-environment & repo normalization (uv/ruff/pytest + branch policies across all repos) | Days 31–70 |
| 2 | Docs & agentic workflows (auto-sync live; ADW on ≥2 repos) | Days 55–100 |
| 3 | GitHub → ADO consolidation (prefect-infra, dbt now; mars post-go-live) | Days 75–125 |
| 4 | Access-governance hardening (grant the CI identity full read; drift fully live) | Days 90–140 |
| 5 | GCP decision & (conditional) migration | Days 120–280 |
| 6 | Contractor onboarding & steady state | Days 140+ |
Two hard timing constraints: the mars repo migration must wait until after its Aug-15 go-live, and the GCP go/no-go must wait for real bill data + a Document AI proof-of-concept — do not pre-commit either.
7. Governance & Success Metrics (summary)
Full RACI and the 12-metric scorecard are in Chapter G, §G5. The essentials:
- Accountability shifts to the PO for ratifying standards, cost, and migration go/no-go; the Dev Lead remains Responsible for execution; ABS is the external Azure-admin partner for tenant/sub-level actions.
- Standing cadence: daily digest review · weekly PO/Dev-Lead sync · monthly access review · quarterly credential cleanup · half-yearly GCP/tech-stack revisit.
- Headline metrics (Day-90 baseline → Day-180 goal): developer onboarding < 1 day → < 4 hrs · new-repo scaffold < 2 hrs → < 1 hr · % repos on standard 60% → 100% ·
lat checkpass 100% (CI-gated) · drift alerts actioned within 1 business day → 100% · GCP bill → $0 (if go) or dated no-go ADR.
8. Key Risks & Mitigations
| Risk | Impact | Mitigation |
|---|---|---|
| Key-person concentration (kgray) | Every grant, review, and deploy bottlenecks on one person | Decisions 13 & 14 (PO gets Reader; second approver); the RACI names owners; the standards themselves are the knowledge transfer |
| Document AI has no clean Azure parity | GCP migration's single biggest technical unknown | Gate the GCP go decision on a real extraction PoC (100 invoices) before committing (G1) |
Migrating mars could destabilize its launch | Live product risk | Hard rule: mars moves to ADO only after Aug-15 go-live (G2, Phase 3) |
| ABS dependency for tenant/sub actions | External turnaround can block onboarding & the drift RBAC grant | Formalize requests with the §E template + ADO queue; batch the outstanding CI-identity RBAC grant into Phase 4 |
| Standards decay if not enforced | We end up back here in a year | Enforcement is mechanical where possible: lat check in CI, branch policies, the template, and the thin CLI making the standard the easy path |
| Contractor security/IP exposure | Data leakage, unclear ownership, un-operable handoffs | The §F isolation-sandbox model, mandatory docs set, and offboarding checklist |
9. Recommended Next Step
Ratify this package (Section 5 register), name the standards owner, and set the two migration decision dates. Phase 0 can begin the day the register is signed — nothing in it requires the migrations to be decided first.
Detailed chapters: A — ADO · B — Dev env & CLI · C — Docs · D — Agentic · E — Access · F — Contractors · G — Migration & roadmap · H — API testing