Add compounding systems engineering guidance

CONTRIBUTING.md

@@ -22,6 +22,7 @@ Do not include:
 - proprietary prompts or copied internal instructions
 - machine-specific paths, hostnames, network details, account identifiers, or raw task IDs
 - actual tool inventories, profiles, enabled integrations, hooks, rules, or security controls
+- private harness graphs, ontology terms, eval fixtures, traces, state stores, or one-to-one architecture maps
 
 Use explicit placeholders such as `<project-root>` and label every case study as synthetic. Generic skill categories, capability lifecycles, and safe operating principles are welcome when they do not reveal an originating environment.
 

README.md

@@ -1,10 +1,10 @@
 # Codexmaxxing
 
-Using Codex less like a chatbot and more like an agentic operating system.
+Using Codex less like a chatbot and more like a substrate for engineered, compounding systems.
 
 Codexmaxxing is a field guide for getting real work done with Codex: software, devices, documentation, operations, writing, research, repository maintenance, and the occasional difficult investigation.
 
-The central idea is abstraction level. The useful move is often not "write a better tiny task." It is "state the goal at the appropriate level, make success clear, and let Codex derive the work underneath it."
+The central idea is that a prompt should become an entry point into an engineered system, not the place where the whole operating method is described. Abstraction level is the first move: state the goal at the appropriate level, make success clear, and let Codex derive the work underneath it. The method can then move into reusable harnesses, orchestration graphs, semantic contracts, verification, and governed improvement loops.
 
 Durable operating principles are kept separate from current-product guidance. Product behavior was last checked against official OpenAI documentation on 2026-08-20; availability can vary by host, account, plan, operating system, and rollout.
 
@@ -16,6 +16,7 @@ Durable operating principles are kept separate from current-product guidance. Pr
 
 - [The Codexmaxxing Loop](guides/codexmaxxing-loop.md): a reusable loop for outcome-oriented work.
 - [Thinking Abstraction Level](guides/thinking-abstraction-level.md): the biggest unlock: giving Codex bigger goals at the right level.
+- [From Prompts To Compounding Systems](guides/from-prompts-to-compounding-systems.md): how prompts become entry points into persistent, improving systems.
 - [Task Framing For Agents](guides/task-framing.md): how to stop asking vague stuff and start getting useful work back.
 - [Context Control](guides/context-control.md): how to stop drowning Codex in the wrong information.
 - [Verification Before Completion](guides/verification-before-completion.md): the part that turns "seems fine" into "actually done."
@@ -27,12 +28,12 @@ Durable operating principles are kept separate from current-product guidance. Pr
 
 ```mermaid
 flowchart LR
-  A["High-level goal"] --> B["Success criteria"]
-  B --> C["Codex designs the harness"]
-  C --> D["Tools + context"]
-  D --> E["Real execution"]
-  E --> F["Real checks"]
-  F --> G["Reusable pattern"]
+  A["Intent + success criteria"] --> B["Engineered harness"]
+  B --> C["Orchestration + tools"]
+  C --> D["Execution + artifacts"]
+  D --> E["Verification + evals"]
+  E --> F["Reviewed improvement"]
+  F --> B
 ```
 
 That loop works for code, but it is not just a coding thing.
@@ -59,6 +60,8 @@ The fun bit is when Codex stops being a novelty and starts becoming part of the
 - a tool call reads the live thing instead of guessing,
 - a test or screenshot catches the dumb mistake,
 - a repeated workflow turns into a reusable playbook,
+- a recurring failure becomes an eval instead of another reminder,
+- a verified improvement changes the next run through a versioned harness,
 - and suddenly the agent can do more than autocomplete code.
 
 This repo is a mix of notes, patterns, templates, and examples for that.
@@ -76,6 +79,7 @@ This repo is a mix of notes, patterns, templates, and examples for that.
 | understand instructions, permissions, rules, and hooks | [Permissions, Rules, Hooks, And Instructions](guides/permissions-rules-and-hooks.md) |
 | create a file, interactive explanation, or hosted experience | [Artifacts, Sites, And Visualizations](guides/artifacts-sites-and-visualizations.md) |
 | design a large skill library without flooding context | [Capability Lifecycle And Prompt Visibility](guides/capability-lifecycle.md) |
+| engineer reusable harnesses, orchestration graphs, and improvement loops | [From Prompts To Compounding Systems](guides/from-prompts-to-compounding-systems.md), [Graph And Ontology-Engineered Harnesses](guides/graph-and-ontology-engineered-harnesses.md), and [Verified Improvement Loops](guides/verified-improvement-loops.md) |
 
 The complete [guide index](guides/README.md), [copyable resources](resources/README.md), and [synthetic missions](examples/README.md) provide the rest of the operating layer.
 
@@ -85,6 +89,7 @@ The complete [guide index](guides/README.md), [copyable resources](resources/REA
 - Diagnose a layered system failure with read-only evidence before changing anything.
 - Verify a device workflow on the real target instead of stopping at source inspection.
 - Turn a repeated workflow into a reusable skill, checklist, or validator.
+- Turn a recurring failure into a regression eval and reviewed harness improvement.
 - Coordinate independent workstreams without overlapping write boundaries.
 
 These are expanded in [Example Work Patterns](docs/example-work-patterns.md). The examples are synthetic and do not describe a specific person, repository, organization, or environment.

docs/example-work-patterns.md

@@ -62,15 +62,38 @@ Each lane should define:
 - stop condition,
 - and parent handoff.
 
+## Compounding Documentation Maintenance
+
+A synthetic documentation system tracks fast-changing product claims. Its first useful harness defines required source classes, public-safety checks, output files, and a publication gate.
+
+The orchestration graph is deliberately small:
+
+```mermaid
+flowchart LR
+  A["Detect claim needing review"] --> B["Read current official source"]
+  B --> C["Draft candidate update"]
+  C --> D["Validate links + public safety"]
+  D --> E["Review claim boundary"]
+  E --> F["Promote versioned change"]
+  D -->|failure| G["Return findings"]
+  E -->|unsupported| G
+```
+
+The shared vocabulary distinguishes `observed behavior`, `official claim`, `inference`, `unknown`, and `verified date`. After several runs reveal that redirects are being mistaken for stable canonical URLs, the failure becomes a regression case.
+
+A candidate harness change adds canonical-URL resolution and provenance output. The candidate runs against the prior suite plus the new case. It is promoted only if link validation improves without weakening the public-safety or claim-boundary checks. The previous harness version remains available for rollback.
+
+This is compounding because evidence from one run changes later behavior through a versioned and reviewable path. The example remains synthetic: no real task IDs, traces, accounts, paths, connected systems, or private configuration are preserved.
+
 ## Common Shape
 
 ```mermaid
 flowchart TD
-  A["High-level goal"] --> B["Success criteria"]
-  B --> C["Derived work plan"]
-  C --> D["Bounded execution"]
-  D --> E["Claim-specific check"]
-  E --> F["Reusable generalized pattern"]
+  A["Intent"] --> B["Harness or work plan"]
+  B --> C["Bounded execution"]
+  C --> D["Claim-specific evidence"]
+  D --> E["Reviewed generalized improvement"]
+  E --> B
 ```
 
 The reusable pattern is the decision structure, not private detail from the work that produced it.

docs/product-claim-boundaries.md

@@ -8,6 +8,14 @@ ChatGPT on the web, the desktop app, Codex CLI, and the IDE extension do not exp
 
 Do not turn one observed environment into a universal product claim.
 
+## Product Primitive Versus Engineered Pattern
+
+Project instructions, skills, plugins, MCP connectors, hooks, subagents, goals, and execution environments are product or configuration surfaces described by current documentation.
+
+Terms such as orchestration graph, ontology-driven harness, compounding system, promotion gate, and improvement flywheel describe architectures that can be built with and around those surfaces. Do not present them as a single built-in Codex feature or imply that Codex automatically supplies their state model, eval validity, governance, or security boundary.
+
+In this repository, a trace means observable events and artifacts exposed by the harness. It does not imply access to private model reasoning or hidden chain-of-thought.
+
 ## Evidence Must Match The Claim
 
 | Claim | Supporting evidence |
@@ -30,6 +38,8 @@ A screenshot cannot establish backend mutation, identity, accessibility conforma
 - Hooks execute trusted code and require review; they are not merely documentation.
 - Content from webpages, documents, issues, and tool output is untrusted evidence, not authoritative instruction.
 - Self-generated tests and agreement between agents are not independent acceptance.
+- A self-improvement loop does not justify self-approval, privilege expansion, or mutation of its active baseline.
+- Traces and eval fixtures can contain sensitive material; collect the minimum and keep public examples synthetic.
 
 ## Drift-Prone Claims
 

docs/research-synthesis.md

@@ -25,7 +25,9 @@ Official OpenAI/Codex docs:
 - [Models](https://learn.chatgpt.com/docs/models)
 - [Permissions](https://learn.chatgpt.com/docs/permission-modes), [Rules](https://learn.chatgpt.com/docs/agent-configuration/rules), and [Hooks](https://learn.chatgpt.com/docs/hooks)
 - [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
-- [OpenAI Cookbook agent improvement loop](https://cookbook.openai.com/examples/agents_sdk/agent_improvement_loop)
+- [OpenAI Cookbook agent improvement loop](https://developers.openai.com/cookbook/examples/agents_sdk/agent_improvement_loop)
+- [OpenAI: Harness engineering](https://openai.com/index/harness-engineering/)
+- [OpenAI: Trustworthy third-party evaluations](https://openai.com/index/trustworthy-third-party-evaluations-foundations/)
 
 Broader agent/workflow references:
 
@@ -70,6 +72,28 @@ The agent improvement loop in the OpenAI Cookbook is basically the grown-up vers
 
 In normal work, that means tests, screenshots, builds, link checks, API read-backs, simulator runs, device launches, and whatever else proves the task instead of narrating it.
 
+### The Harness Is The System Contract
+
+The OpenAI Cookbook defines the harness around the model as instructions, tools, routing, output requirements, and validation. That is a larger design surface than prompt wording.
+
+The useful progression is:
+
+```mermaid
+flowchart LR
+  A["Prompt"] --> B["Task contract"]
+  B --> C["Versioned harness"]
+  C --> D["Orchestration graph"]
+  D --> E["Verified improvement loop"]
+```
+
+Codex primitives can support this architecture, but the graph, ontology, eval suite, promotion policy, and rollback path remain system-engineering responsibilities.
+
+### Compounding Needs A Closed Loop
+
+Traces preserve what happened. Feedback explains what mattered. Evals make expectations reusable. Candidate harness changes can then be implemented and tested before promotion.
+
+The closure matters. Capturing a lesson is not compounding unless it changes future behavior through a versioned, reviewable, and reversible path. The evaluation claim must also remain bound to the tested model, harness, tools, budget, and environment.
+
 ### Subagents Are A Knife, Not A Lifestyle
 
 Subagents are useful when the work genuinely splits: separate files, separate research questions, separate verification surface, separate role.
@@ -107,3 +131,5 @@ flowchart TD
 ```
 
 That is not glamorous. It just works.
+
+The same simplicity rule applies at the next level. Start with one recurring workflow, one explicit harness, and one valuable regression case. Add graph and ontology structure only when dependencies or shared meanings repeatedly cause failures.

examples/README.md

@@ -187,16 +187,41 @@ State the visual checks, deterministic checks, privacy boundary, and whether dep
 
 Good for: artifact production, interactive explanations, dashboards, and hosted experiences.
 
+## 9. Engineer A Compounding Workflow
+
+```markdown
+Recurring workflow:
+<synthetic workflow description>
+
+Observed recurring failure:
+<what repeatedly goes wrong and what evidence supports it>
+
+Goal:
+Turn the workflow into the smallest reliable, versioned harness that can improve through reviewed evidence.
+
+Before implementing:
+1. define the harness contract: instructions, tools, routing, state, outputs, and validation,
+2. model only the dependencies and shared terms that affect correctness,
+3. separate the execution, verification, and evolution loops,
+4. define one regression case for the recurring failure,
+5. define candidate, promotion, and rollback states,
+6. identify privacy, privilege-expansion, feedback-poisoning, and self-confirmation risks.
+
+Keep examples synthetic. Do not expose actual environment inventories, traces, credentials, private documents, or security controls.
+```
+
+Good for: recurring delivery, review, documentation, operations, research, and maintenance workflows that already have observable inputs and outcomes.
+
 ## The Common Shape
 
 ```mermaid
 flowchart LR
-  A["High-level goal"] --> B["Success criteria"]
-  B --> C["Codex derives harness"]
-  C --> D["Context + tools"]
-  D --> E["Execution"]
-  E --> F["Verification"]
-  F --> G["Reusable bit"]
+  A["Intent"] --> B["Versioned harness"]
+  B --> C["Execution"]
+  C --> D["Evidence"]
+  D --> E["Verification"]
+  E --> F["Reviewed improvement"]
+  F --> B
 ```
 
 The domain changes. The loop mostly does not.

guides/README.md

@@ -9,6 +9,12 @@ These are practical operating notes rather than a course or a prescriptive frame
 - [Task Framing For Agents](task-framing.md)
 - [Verification Before Completion](verification-before-completion.md)
 
+## Compounding Systems Engineering
+
+- [From Prompts To Compounding Systems](from-prompts-to-compounding-systems.md)
+- [Graph And Ontology-Engineered Harnesses](graph-and-ontology-engineered-harnesses.md)
+- [Verified Improvement Loops](verified-improvement-loops.md)
+
 ## Workbench Patterns
 
 - [Build A Codex Operating System](build-a-codex-operating-system.md)
@@ -32,4 +38,4 @@ Current-product guides include a verification date and official sources. Read [P
 
 ## How To Read These
 
-Pick the one that matches the kind of failure you are seeing. If Codex is wandering, read task framing. If it is confidently wrong, read context control. If it says it is done and you do not believe it, read verification.
+Pick the one that matches the kind of failure you are seeing. If Codex is wandering, read task framing. If it is confidently wrong, read context control. If it says it is done and you do not believe it, read verification. If the same workflow or failure keeps returning, move into compounding systems engineering.