Agentic Engineering
The working canon for the discipline of constructing engineering environments in which code ships to production safely and continuously — an environment that’s good for humans and AI both.
Guiding principle: What is good for humans is good for the AI.
The gap between “AI can write code” and “AI actually ships production value with trust” isn’t a model-capability problem — it’s an engineering-environment problem. This repo is where we reason about that environment, codify it into a rubric, and dogfood the rubric’s own principles on the repo itself.
What’s here
The repo organises around three content trees (by publish-scope and lifecycle) plus code subsystems:
canon/ — public content
Published to safeagentic.org.
| Path | What it is |
|---|---|
canon/agentic-engineering-rubric.md | The rubric itself — 50 criteria across five pillars (Focus, Validation, Actions, Safe Space, Workflow), scored 0–3 with a Compounding level, plus four meta-metrics and a Risk Floor rule. Current version: v0.27. The evaluation instrument; diagnostic, not prescriptive. |
canon/recipes/ | Reusable mechanisms that advance specific rubric criteria. Each recipe is an abstract pattern (bot-token credential tenancy, GitOps JIT elevation, indexed per-entry registry) with prerequisites, failure modes, case studies. The prescriptive layer. |
internal/ — internal work product and events (frozen-shape)
Never published externally. Work product and historical events that inform the canon’s public surface.
| Path | What it is |
|---|---|
internal/features/ | Forward-looking plans for work we intend to do — scope, acceptance criteria, task breakdown, dependencies, rubric-dogfood targets. Realises rubric PL1-task-decomposition level-2’s feature-template requirement. |
internal/research/ | First-class tech-research tasks. Each research doc is an investigation — question, scope, method, findings, negative findings, recommendations. Produces recipe promotions, rubric refinements, ADRs. |
internal/references/ | External authoritative source material: standards, specifications, vendor docs, academic papers. The canon’s primary-source library; three copyright tiers (open / restricted / proprietary) handled distinctly. |
internal/integrations/ | Wired-up instances of recipes — specific Slack workspaces, CF projects, token scopes. Project-specific; produced when features ship. |
internal/conversations/ | Records of thinking sessions (typically solo or informal). Frozen once captured. Inputs to research, features, memory updates. |
internal/briefings/ | Prep for outbound engagements with named recipients — reviews, walkthroughs, presentations. Frozen post-engagement. |
memory/ — evolving process state
Distinguished from internal/ by lifecycle: memory entries are revised as understanding grows.
| Path | What it is |
|---|---|
memory/stakeholders/ | Who we work with — role, preferences, history, prior engagements. Living documents that evolve with the relationship. |
Code subsystems (lazy-created)
Standard monorepo convention — each service / app owns its own source + tests + generated artefacts.
| Path | What it is |
|---|---|
apps/web/ | The site that publishes canon/ to safeagentic.org. Astro + Starlight; deploys to Cloudflare Pages. |
services/ | Backend runtime services. Future: services/substrate/ (memory-substrate MCP server). |
packages/changesets/ | Changeset validator (changeset-check) and compiler (changeset-release) CLIs. Enforces the .changeset/ schema on every PR; compiles pending changesets into CHANGELOG.md at release cut. |
infra/ | Infrastructure-as-code (OpenTofu). Future, per internal/features/canon-web-infra.md. |
ops/ | Operational runtime artefacts — pin files, digest manifests, operational scripts. Future, per internal/features/canon-ci-runner.md. |
CHANGELOG.md | Aggregated release history in Keep a Changelog format. One release block per completed feature. Updated by changeset-release; not hand-edited. |
Status
- Rubric v0.27 — post-restructure. Structure stable; recipes layer separates prescriptive mechanisms from the rubric’s evaluation scope; structural-enforcement-over-procedural-gating principle codified at the Philosophy level.
- First external review: Li Theen, tech lead — retained as
internal/research/rubric-review-v0.16.md. - Target: lock v1.0 within two weeks, baseline against SinarAI/Surge and Gentari.
How the repo dogfoods the rubric
The repo is itself the first project scored against the canon:
- Focus (P1) — each folder has a single job; stakeholder memory consolidates context so a reviewer briefing is a one-file read.
- Validation (P2) — the rubric’s own Open Questions section is its pre-commit gate;
apps/web/has test-first specifiable units (schemas, slicers, link rewriters). - Actions (P3) — stakeholder frontmatter carries
contactblocks; integration records describe wired-up scopes. - Safe Space (P4) — public/internal/memory split at the folder level makes publish-scope structural;
.gitignoreexcludes sensitive binaries. - Workflow (P5) — conversations are events recorded in
internal/conversations/; the template-evolution log ininternal/features/README.mdtracks template drift.
Provenance
Traces back to the Granola discussion on 16 April 2026 between Jason Khong and Li Theen — see internal/conversations/2026-04-16-agentic-engineering-origin.md.