diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe83c43..7534f53 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ Thanks for improving Codexmaxxing. This repo is a public guide, so changes shoul ## Keep It Anonymous And Public-Safe -Use neutral editorial language and synthetic or composite examples. Examples must not map one-to-one to a real person, repository, organization, or environment. +Use natural, generalized public language and synthetic or composite examples. First-person opinions are fine; autobiographical detail, private incidents, and examples that map one-to-one to a real person, repository, organization, or environment are not. Do not include: @@ -22,7 +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 +- private workflow graphs, internal vocabularies, eval fixtures, traces, state stores, or one-to-one architecture maps Use explicit placeholders such as `` 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. diff --git a/README.md b/README.md index 47579cf..adb3a3a 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Codexmaxxing -Using Codex less like a chatbot and more like a substrate for engineered, compounding systems. +A practical guide to using Codex for real work—and turning the workflows that matter into reliable, reusable 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 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. +The pattern I keep coming back to is simple: say what should be true, make the important boundaries clear, and let Codex work out the path underneath. For a one-off task, that may be all you need. When the same work keeps coming back, the useful parts can move into instructions, skills, scripts, checks, and other reusable pieces so the next run starts stronger. 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. @@ -14,26 +14,24 @@ Durable operating principles are kept separate from current-product guidance. Pr ## Start Here -- [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." -- [Example Missions](examples/README.md): a few shapes for real work, including non-code work. -- [Example Work Patterns](docs/example-work-patterns.md): synthetic examples of the patterns in practice. -- [Product Claim Boundaries](docs/product-claim-boundaries.md): what each kind of evidence can and cannot prove. +If you want to use Codex better today, start with [The Codexmaxxing Loop](guides/codexmaxxing-loop.md), [Thinking Abstraction Level](guides/thinking-abstraction-level.md), and the [Example Missions](examples/README.md). + +If the same workflow or failure keeps returning, move into [From Prompts To Compounding Systems](guides/from-prompts-to-compounding-systems.md). That is where the guide gets into reusable harnesses, workflow graphs, shared vocabularies, evals, and controlled improvement. + +If you are trying to understand a current Codex feature—such as projects, scheduled tasks, skills, plugins, subagents, worktrees, Browser, or Computer Use—use the [complete guide index](guides/README.md). Product-specific pages are dated and link back to current official sources. ## The Shape Of It ```mermaid flowchart LR - 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 + A["Ask for an outcome"] --> B["Inspect what matters"] + B --> C["Do the work"] + C --> D["Check the result"] + D --> E{"Likely to repeat?"} + E -->|no| F["Finish honestly"] + E -->|yes| G["Make the useful part reusable"] + G --> H["Test the next version"] + H --> B ``` That loop works for code, but it is not just a coding thing. @@ -55,18 +53,18 @@ The fun bit is when Codex stops being a novelty and starts becoming part of the - a repo has instructions that actually help, - a goal has success criteria, -- Codex can derive the task contract instead of requiring every field to be written in advance, -- parallel projects have status contracts instead of vibes, +- Codex can work out a sensible plan without every step being written in advance, +- parallel work has clear owners, boundaries, and handoffs instead of vibes, - 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, +- a tested improvement makes the next comparable run better, - and suddenly the agent can do more than autocomplete code. This repo is a mix of notes, patterns, templates, and examples for that. -## Choose The Surface +## Choose What You Need | If you want to... | Start with | | --- | --- | @@ -79,9 +77,9 @@ 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) | +| turn repeated work into a system that can improve safely | [From Prompts To Compounding Systems](guides/from-prompts-to-compounding-systems.md), [Workflow Graphs, Shared Vocabulary, And 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. +The complete [guide index](guides/README.md), [copyable resources](resources/README.md), and [synthetic missions](examples/README.md) provide the rest. ## Synthetic Work Patterns @@ -89,7 +87,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. +- Turn a recurring failure into a regression eval and a reviewed workflow 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. @@ -100,7 +98,7 @@ Codexmaxxing is in public alpha. The durable operating patterns are intended for Known limitations: -- Codex surfaces and availability can differ by host, plan, account, operating system, and rollout. +- Codex features and availability can differ by host, plan, account, operating system, and rollout. - Examples are synthetic teaching material, not evidence that a workflow will fit every environment. - Automated validation catches defined content and repository risks but cannot prove complete anonymity, factual completeness, accessibility, or visual quality. - There is no versioned release, compatibility guarantee, or support service. diff --git a/assets/agentic-harness-topologies.svg b/assets/agentic-harness-topologies.svg index 3ac89ba..eb26843 100644 --- a/assets/agentic-harness-topologies.svg +++ b/assets/agentic-harness-topologies.svg @@ -1,5 +1,5 @@ - Agentic harness topologies + Ways to structure parallel Codex work Four simple shapes for running Codex work: single-thread, hub-and-spoke, pipeline, and portfolio board. @@ -24,11 +24,11 @@ - Agentic harness topologies - Pick the shape first. Handoffs, proof, and integration follow the topology. + Ways to structure parallel Codex work + Pick a shape that fits the work. Handoffs, checks, and integration follow. - Single-thread harness + Single task Best when judgment is tight or the edit is risky. Goal @@ -38,7 +38,7 @@ Check - One owner, one loop, clean proof. + One owner, one loop, clear evidence. Hub-and-spoke @@ -74,7 +74,7 @@ Portfolio board - Best for multiple projects with separate proof paths. + Best for multiple projects with separate checks. Board @@ -83,8 +83,8 @@ Project 2 - Proof queue + Review queue - State, blockers, next proof. Nothing fancier unless it earns it. + State, blockers, next check. Nothing fancier unless it earns it. diff --git a/assets/codexmaxxing-loop.svg b/assets/codexmaxxing-loop.svg index 872c420..d3e42c8 100644 --- a/assets/codexmaxxing-loop.svg +++ b/assets/codexmaxxing-loop.svg @@ -32,7 +32,7 @@ Codexmaxxing Use Codex like an agentic operating system: clear goals in, verified work out. - goal -> harness -> proof + goal -> work -> check @@ -64,11 +64,11 @@ 02 - AGENTIC HARNESS - Derive the system + WORK PLAN + Work out the path - Task contract, context map, topology, - delivery path, checks, and stop rules. + Sources, steps, work split, + checks, and stop conditions. @@ -77,7 +77,7 @@ 03 WORKBENCH - Load the surface + Load what matters Repo files, docs, browser, MCP, APIs, live systems, examples, and memory. @@ -100,7 +100,7 @@ 05 - REAL PROOF + REAL CHECK Verify the thing Tests, screenshots, builds, read-backs, @@ -123,11 +123,11 @@ the maxxing move - delegate the harness, not just the tiny edit + delegate the outcome, not just the tiny edit - The loop gets better when each pass leaves behind a sharper harness: better context, better checks, better tools, better delegation. + The loop gets better when repeated work leaves behind better context, checks, tools, and delegation. diff --git a/assets/review-manifest.json b/assets/review-manifest.json index 8bafd6c..7256769 100644 --- a/assets/review-manifest.json +++ b/assets/review-manifest.json @@ -4,7 +4,7 @@ "assets": [ { "path": "assets/agentic-harness-topologies.svg", - "sha256": "0c560e4cc19b56bb80386056332b12c73960a6e5e714c31adf87561042d51256", + "sha256": "83f0b4fc0d091f3f93c6f5b7ffb8c0ec32286479d581bc98ede376e781ffda49", "checks": ["metadata", "privacy", "visual"] }, { @@ -14,7 +14,7 @@ }, { "path": "assets/codexmaxxing-loop.svg", - "sha256": "ca66bfac49c1fc4d4ea39953f33cf3c8d3389d2b268c6749e05ae4d08d59e098", + "sha256": "db29af52ce6782f9920932c76ddbd4c52becb34ca422ea746698156f6fa96a53", "checks": ["metadata", "privacy", "visual"] }, { @@ -24,7 +24,7 @@ }, { "path": "assets/thinking-abstraction-level.svg", - "sha256": "9d06aa9d702511392c247e1a4f00406b4ccf0f739e7209a8dff84a81204d10ee", + "sha256": "a2fa3757dedfe6f90d5491f56f2d1f87f405c776f18c88fa7bd94f0b04e7ef33", "checks": ["metadata", "privacy", "visual"] } ] diff --git a/assets/thinking-abstraction-level.svg b/assets/thinking-abstraction-level.svg index b54017c..5cb69d7 100644 --- a/assets/thinking-abstraction-level.svg +++ b/assets/thinking-abstraction-level.svg @@ -1,6 +1,6 @@ Thinking Abstraction Level ladder - A ladder showing movement from tiny tasks to broad goals where Codex derives the project and delivery harness. + A ladder showing movement from tiny tasks to broad goals where Codex works out more of the path. @@ -26,13 +26,13 @@ L0: Do this exact edit - useful, but you carry the plan + useful, but you carry the plan L1: Complete this task - Codex follows the frame + Codex follows the frame L2: Design the approach - task contract, checks, slices + plan, checks, work split L3: Achieve this outcome - project + delivery harness + Codex owns more of the path diff --git a/docs/example-work-patterns.md b/docs/example-work-patterns.md index c38b377..47b0804 100644 --- a/docs/example-work-patterns.md +++ b/docs/example-work-patterns.md @@ -30,13 +30,13 @@ The safe pattern is: 2. identify evidence that distinguishes the layers, 3. gather the least-sensitive evidence first, 4. make the smallest reversible change, -5. read the affected surface back. +5. read the affected system back. ## Device Workflow An application communicates with an external device. A plausible source change is not enough to prove that the workflow works. -Verification may need to cross several surfaces: +Verification may need to cross several layers: ```mermaid flowchart LR @@ -47,7 +47,7 @@ flowchart LR E --> F["Observed result"] ``` -The final claim should state exactly which surfaces were checked and which remain unverified. +The final claim should state exactly which layers were checked and which remain unverified. ## Parallel Workstreams @@ -64,9 +64,9 @@ Each lane should define: ## 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. +A synthetic documentation system tracks fast-changing product claims. Its first useful reusable workflow defines required source types, public-safety checks, output files, and a publication gate. -The orchestration graph is deliberately small: +The workflow graph is deliberately small: ```mermaid flowchart LR @@ -74,14 +74,14 @@ flowchart LR B --> C["Draft candidate update"] C --> D["Validate links + public safety"] D --> E["Review claim boundary"] - E --> F["Promote versioned change"] + E --> F["Approve 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. +A proposed workflow change adds canonical-URL resolution and records where each result came from. It runs against the prior suite plus the new case. It is adopted only if link validation improves without weakening the public-safety or claim-boundary checks. The previous 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. @@ -89,7 +89,7 @@ This is compounding because evidence from one run changes later behavior through ```mermaid flowchart TD - A["Intent"] --> B["Harness or work plan"] + A["Intent"] --> B["Reusable workflow or work plan"] B --> C["Bounded execution"] C --> D["Claim-specific evidence"] D --> E["Reviewed generalized improvement"] diff --git a/docs/field-synthesis.md b/docs/field-synthesis.md index efcd74c..7e5ec11 100644 --- a/docs/field-synthesis.md +++ b/docs/field-synthesis.md @@ -4,17 +4,22 @@ These generalized patterns recur across software, operations, devices, documenta The examples are synthetic and do not describe a specific person, repository, organization, or environment. -The central pattern is abstraction level. As models become more capable, a well-bounded goal can delegate more of the decomposition while the operator retains responsibility for scope, permissions, and verification. +The central pattern is choosing the right abstraction level, then checking the real result. As models become more capable, a well-bounded goal can delegate more of the path while the operator retains responsibility for scope, permissions, and verification. ```mermaid flowchart TD A["Choose abstraction level"] --> B["Goal + success criteria"] - B --> C["Derive work contract"] + B --> C["Work out the plan"] C --> D["Design bounded approach"] D --> E["Execute"] E --> F["Human or system verifies"] + F --> G{"Likely to repeat?"} + G -->|no| H["Finish"] + G -->|yes| I["Test a reusable improvement"] ``` +The improvement branch is optional. A one-off task can finish after honest verification. Repeated work is where instructions, skills, scripts, evals, and other reusable pieces start to pay off. + ## Live Systems: Read First, Then Touch Things A reliable operations loop is deliberately conservative: @@ -51,15 +56,15 @@ That often means: When a workflow repeats, preserve the generalized method as a skill, checklist, template, or validator. Do not preserve the private source material that produced it. -## Parallel Work: Topology Before Swarm +## Parallel Work: Shape Before Swarm -Parallel work becomes useful when each stream has a contract, not merely when more agents are running. +Parallel work becomes useful when each stream has a clear job and handoff, not merely when more agents are running. The durable pattern is: -- choose the topology, +- choose the work shape, - split by ownership boundary, -- give every stream a status contract, +- give every stream a simple update format, - keep the parent responsible for integration, - verify each result before treating it as progress. diff --git a/docs/research-synthesis.md b/docs/research-synthesis.md index adc2fca..4812e9c 100644 --- a/docs/research-synthesis.md +++ b/docs/research-synthesis.md @@ -6,7 +6,7 @@ Official product sources on this page were last checked on 2026-08-20. Short version: the good stuff happens when you stop treating the model as a magic brain and start giving it a decent operating environment. -One important shift is thinking in terms of abstraction level. Capable models can often take a broad goal with clear success criteria and derive the task contract, project harness, delivery harness, and checks. That changes where human judgment is most valuable. +One important shift is thinking in terms of abstraction level. Capable models can often take a broad goal with clear success criteria and work out the plan and checks. When the work repeats, the stable parts can move into reusable instructions, tools, workflows, and evals. That changes where human judgment is most valuable. ## Sources Worth Reading @@ -44,13 +44,13 @@ The useful human contribution is shifting upward: - less manual decomposition of every tiny task, - more clarity on goals, constraints, taste, and success criteria, - more attention to context, tools, safety, and verification, -- more reuse of skills, harnesses, and operating patterns. +- more reuse of skills, tools, checks, and working patterns. That does not mean vague prompts work. It means high-level goals work when the success criteria and operating boundaries are clear. -### Codex Is A Work Surface +### Codex Is A Workbench -Codex is not just a box that answers questions. The current product surface spans projects and chats, goals and scheduled tasks, Local/Worktree/Cloud environments, skills and plugins, MCP connectors, Browser and Computer Use, artifacts and hosted Sites, permissions, hooks, rules, models, reasoning controls, and subagents. +Codex is not just a box that answers questions. The current product includes projects and tasks, goals and schedules, Local/Worktree/Cloud environments, skills and plugins, MCP connectors, Browser and Computer Use, artifacts and hosted Sites, permissions, hooks, rules, models, reasoning controls, and subagents. That means the leverage is in the setup around the model: the repo, the tools, the docs, the task shape, and the checks. @@ -72,37 +72,37 @@ 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 +### A Harness Is The Setup Around The Model -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 OpenAI Cookbook defines the harness around the model as instructions, tools, routing, output requirements, and validation. In other words, it is the reusable setup that shapes how the model works—not just the prompt. The useful progression is: ```mermaid flowchart LR - A["Prompt"] --> B["Task contract"] - B --> C["Versioned harness"] - C --> D["Orchestration graph"] + A["Prompt"] --> B["Clear work plan"] + B --> C["Reusable harness"] + C --> D["Workflow graph, if needed"] 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. +Codex building blocks can support this architecture, but the workflow graph, shared vocabulary, eval suite, adoption policy, and rollback path remain things the system designer has to provide. ### 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. +Traces preserve what happened. Feedback explains what mattered. Evals make expectations reusable. Proposed harness changes can then be implemented and tested before adoption. -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. +The loop has to close. 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. +Subagents are useful when the work genuinely splits: separate files, separate research questions, separate checks, separate roles. They are not automatically better. Sometimes one focused loop beats a whole little committee. -### Parallelism Needs Topology +### Parallel Work Needs A Clear Shape -The same applies one level up. Multiple agents, custom agents, automations, and parallel project threads only help when the harness topology is clear. +The same applies one level up. Multiple agents, custom agents, automations, and parallel project tasks only help when the work has a clear shape. That means: @@ -123,7 +123,7 @@ For Codex, that usually means: ```mermaid flowchart TD A["Broad goal"] --> B["Success criteria"] - B --> C["Derived harness"] + B --> C["Derived plan"] C --> D["Right context"] D --> E["Tool access"] E --> F["Execution"] @@ -132,4 +132,4 @@ 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. +The same simplicity rule applies at the next level. Start with one recurring workflow, one reusable setup, and one valuable regression case. Add a graph or formal vocabulary only when dependencies or shared meanings repeatedly cause failures. diff --git a/examples/README.md b/examples/README.md index d3a81b4..3eb82d6 100644 --- a/examples/README.md +++ b/examples/README.md @@ -4,31 +4,16 @@ Codexmaxxing makes more sense when it is attached to a well-defined mission. All examples are synthetic. Their names, paths, systems, and evidence are placeholders and do not describe a specific person, repository, organization, or environment. -The point is not to pre-chew every task. Give Codex an appropriate abstraction level, success criteria, and the right context. Let it design the plan underneath. +The point is not to pre-chew every task. Say what you want, make the important limits clear, and let Codex design the plan underneath. Use the amount of structure the work needs; these do not have to become forms. -## 0. Broad Goal: Let Codex Build The Harness +## 0. Broad Goal: Let Codex Work Out The Path ```markdown -Goal: Turn this rough repo into a public-facing project that people can understand, explore, and reuse. -Success criteria: -- the README has a clear point of view, -- the first-click paths are obvious, -- examples include technical and non-technical work, -- examples are synthetic and public-safe, -- internal maintenance notes are not part of the public surface, -- validation still passes. - -Constraints: -- keep the voice casual, practical, and technical, -- avoid work-presentation energy, -- keep private details out. - -Context: -Start with README, docs, guides, resources, and examples. - -Before editing, choose the appropriate abstraction level and derive only the task contract, delivery steps, verification plan, and stop conditions that the work needs. +Start with the README, docs, guides, resources, and examples. Work out the plan before editing. + +The finished repo should have a clear point of view, obvious first-click paths, useful technical and non-technical examples, and passing validation. Keep the voice casual, practical, and technical. Remove internal maintenance framing and keep every example synthetic and public-safe. ``` Good for: repo shaping, product positioning, docs overhaul, public launch prep. @@ -120,12 +105,12 @@ Success criteria: - every delegated stream has a proof path, - the parent thread has clear integration checkpoints. -Design the agentic harness topology first. Then recommend which work should stay with the parent, which should go to subagents or custom agents, and what status contract each stream should use. +Recommend what should stay in the main task, what can safely go to subagents or separate tasks, and how each stream should report progress and evidence. Keep the setup as simple as the work allows. ``` Good for: small portfolios, multi-repository cleanup, launch preparation, and research paired with implementation. -## 6. Choose The Execution Surface +## 6. Choose Where The Work Should Run ```markdown Goal: @@ -166,7 +151,7 @@ Prefer the smallest layer that changes behavior reliably. Keep credentials, actu Good for: turning repeated work into a maintainable operating layer. -## 8. Choose The Output Surface +## 8. Choose The Output Format ```markdown Source material: @@ -196,16 +181,11 @@ Recurring workflow: Observed recurring failure: -Goal: -Turn the workflow into the smallest reliable, versioned harness that can improve through reviewed evidence. +Help me turn this into the smallest reusable workflow that will make later runs more reliable. + +Start simple. Tell me what should stay in the prompt, what belongs in instructions, a skill, a script, or a check, and where human approval still matters. Add a workflow graph or shared schema only if order, branching, recovery, or inconsistent language is causing real problems. -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. +Turn the recurring failure into a regression case. Test any proposed workflow change against the current version before adopting it, keep a rollback path, and check for privacy, broader permissions, bad feedback, and self-confirming tests. Keep examples synthetic. Do not expose actual environment inventories, traces, credentials, private documents, or security controls. ``` @@ -216,12 +196,13 @@ Good for: recurring delivery, review, documentation, operations, research, and m ```mermaid flowchart LR - A["Intent"] --> B["Versioned harness"] - B --> C["Execution"] - C --> D["Evidence"] - D --> E["Verification"] - E --> F["Reviewed improvement"] - F --> B + A["Outcome"] --> B["Work"] + B --> C["Check"] + C --> D{"Likely to repeat?"} + D -->|no| E["Finish"] + D -->|yes| F["Make the useful part reusable"] + F --> G["Test the next version"] + G --> B ``` The domain changes. The loop mostly does not. diff --git a/guides/README.md b/guides/README.md index 68ad51a..151d990 100644 --- a/guides/README.md +++ b/guides/README.md @@ -1,21 +1,21 @@ # Guides -These are practical operating notes rather than a course or a prescriptive framework. Each guide captures a reusable pattern and its limits. +These are practical operating notes, not a course or a framework that every task must follow. Start with the problem you have. -## The Main Loop +## Use Codex Better Today - [The Codexmaxxing Loop](codexmaxxing-loop.md) - [Thinking Abstraction Level](thinking-abstraction-level.md) - [Task Framing For Agents](task-framing.md) - [Verification Before Completion](verification-before-completion.md) -## Compounding Systems Engineering +## Turn Repeated Work Into A System - [From Prompts To Compounding Systems](from-prompts-to-compounding-systems.md) -- [Graph And Ontology-Engineered Harnesses](graph-and-ontology-engineered-harnesses.md) +- [Workflow Graphs, Shared Vocabulary, And Harnesses](graph-and-ontology-engineered-harnesses.md) - [Verified Improvement Loops](verified-improvement-loops.md) -## Workbench Patterns +## Build A Reusable Codex Setup - [Build A Codex Operating System](build-a-codex-operating-system.md) - [Context Control](context-control.md) @@ -25,7 +25,7 @@ These are practical operating notes rather than a course or a prescriptive frame - [Delegation And Subagents](delegation-and-subagents.md) - [Team Adoption](team-adoption.md) -## Current Product Surfaces +## Understand Current Codex Capabilities - [Projects, Chats, Goals, And Scheduled Tasks](projects-chats-goals-and-schedules.md) - [Local, Worktree, And Cloud Environments](environments-worktrees-and-cloud.md) diff --git a/guides/artifacts-sites-and-visualizations.md b/guides/artifacts-sites-and-visualizations.md index c588434..660775c 100644 --- a/guides/artifacts-sites-and-visualizations.md +++ b/guides/artifacts-sites-and-visualizations.md @@ -36,7 +36,7 @@ Every Sites deployment URL is a production deployment. Save a version without de Treat deployment as an external write. Verify the intended content, data boundary, authentication assumptions, and production URL after publication. -## Review Contract +## Review Requirements ```markdown Output type: diff --git a/guides/browser-computer-use-and-connectors.md b/guides/browser-computer-use-and-connectors.md index 67763ef..ed86aea 100644 --- a/guides/browser-computer-use-and-connectors.md +++ b/guides/browser-computer-use-and-connectors.md @@ -31,7 +31,7 @@ Operating-system screen and accessibility permissions are separate from ChatGPT Prefer the built-in Browser first for a local web application. Prefer a dedicated connector for structured data access. Use Computer Use when visual state is part of the task. -## Safe Operating Contract +## Safe Operating Rules ```markdown Target application or site: diff --git a/guides/build-a-codex-operating-system.md b/guides/build-a-codex-operating-system.md index 5f91ef0..2c11808 100644 --- a/guides/build-a-codex-operating-system.md +++ b/guides/build-a-codex-operating-system.md @@ -1,71 +1,56 @@ # Build A Codex Operating System -Codex gets stronger when the surrounding setup tells it what matters, gives it room to think at the right abstraction level, and preserves verified improvements across runs. +Codex gets stronger when the surrounding setup tells it what matters, gives it room to think at the right abstraction level, and keeps the useful parts of earlier work. That setup does not need to be heavy. Most of the time it is just a few files, a few habits, and one or two checks that stop the agent from wandering off into the bushes. -## The Nine System Layers +## Start Light -### 1. Intent And Authority +Most projects need five things. -Start by choosing the level of the ask. Are you asking for an exact edit, a framed task, an outcome, or a system objective? - -Name who can request the work, what may be read or changed, and which transitions require approval. The higher the abstraction level, the more important explicit success criteria, permission boundaries, and stop conditions become. - -### 2. Mission brief +### 1. Outcome And Boundaries -Every non-trivial mission needs an outcome, source of truth, constraints, verification, and stop conditions. You can write these yourself, but often the better move is to ask Codex to draft them from the goal before execution. - -### 3. Source And Semantic Model - -Name the context that matters: +Start by choosing the level of the ask. Are you asking for an exact edit, a framed task, an outcome, or a system objective? -- repo files and tests, -- current user instruction, -- official docs, -- live APIs or deployed surfaces, -- issue trackers or planning docs, -- prior memory or decisions. +Name what should be true, what Codex may read or change, what is out of scope, and which actions need approval. The higher the abstraction level, the more important clear success criteria and stop conditions become. -Also name what does not matter. Excluding stale or adjacent context is part of the job. +### 2. Sources And Context -For workflows that cross multiple agents or systems, define the terms they must share: entities, states, relationships, provenance, and invariants. A small schema or vocabulary is often enough; do not introduce a large ontology without recurring semantic ambiguity. +Point Codex at the sources that can change the decision: repository files and tests, the current instruction, official documentation, a live API or deployment, or a relevant issue or decision record. -### 4. Instructions And Routing +Also say what does not matter. Excluding stale or adjacent context is part of the job. -Use project instructions for repo-level defaults: coding style, useful commands, privacy boundaries, browser routes, and release gates. Keep them practical. If a rule applies to only one workflow, make it a checklist or skill instead. Keep routing explicit enough that Codex can find the narrow capability without loading the whole library. +### 3. Instructions And Tools -### 5. Capability Surface +Use project instructions for durable local rules: useful commands, coding style, privacy boundaries, and release gates. If a rule applies to one workflow, keep it in that workflow instead of making it global. -Give Codex the smallest capability surface needed for the work: project instructions, scripts, skills, plugins, MCP connectors, Browser, Computer Use, or ordinary shell and Git tools. Start read-only when the state is uncertain. Allow writes only when the source of truth and rollback boundary are clear. See [Skills, Plugins, MCP, And Tools](skills-plugins-mcp-and-tools.md). +Give Codex the smallest set of tools it needs. Start read-only when the state is uncertain. Allow writes only when the source of truth, approval boundary, and rollback path are clear. See [Skills, Plugins, MCP, And Tools](skills-plugins-mcp-and-tools.md). -### 6. Orchestration Graph +### 4. Shape Of The Work -Name both who performs the work and how work moves. Is this one chat, a subagent workflow, separate worktree chats, a delivery pipeline, or a set of cloud tasks? Which dependencies, gates, state transitions, retries, and recovery paths connect them? See [Graph And Ontology-Engineered Harnesses](graph-and-ontology-engineered-harnesses.md) and [Local, Worktree, And Cloud Environments](environments-worktrees-and-cloud.md). +Keep the work in one task when judgment is tightly connected or edits overlap. Split it when the workstreams are genuinely independent and each has a clear owner, output, and integration point. -Do not automate a graph you cannot explain. Each node needs a source of truth, write boundary, status contract, evidence contract, and integration point. +If order, branching, retries, or recovery affect correctness, draw the workflow. Otherwise a short plan is enough. See [Workflow Graphs, Shared Vocabulary, And Harnesses](graph-and-ontology-engineered-harnesses.md) and [Local, Worktree, And Cloud Environments](environments-worktrees-and-cloud.md). -### 7. State, Artifacts, And Evidence +### 5. Checks -Decide which state is task-local, durable, external, derived, or prohibited. Define required outputs and keep unresolved questions visible. Preserve provenance without collecting unnecessary sensitive content. +Define the check before claiming completion. The right check is the one most likely to catch a plausible but wrong result. Use tests for deterministic behavior, rendered or browser inspection for visible behavior, and live read-backs for live state. -### 8. Verification And Observability +## Add Only What Repeats -Define the check before claiming completion and capture enough structured evidence to diagnose failure. The right check is the one most likely to catch the wrong plausible result. A system-level check should also cover invariants, transitions, and recovery paths. +When a workflow keeps coming back, move the stable parts out of the prompt: -### 9. Governed Improvement +- repeated instructions can become project guidance or a skill; +- exact transforms and checks can become scripts or validators; +- useful output shapes can become templates; +- recurring failures can become regression cases; +- recurring handoffs can become a small workflow graph. -Repeated lessons can become reusable artifacts: +If several agents or systems keep disagreeing about terms, define a small shared vocabulary or schema. If the distinction is not causing failures, ordinary prose is enough. -- instructions, -- templates, -- validators, -- scripts, -- skills, -- decision records, -- examples. +Keep only the evidence needed to understand the result and diagnose failure. Do not collect raw prompts, private documents, credentials, or unrestricted traces merely because they might be useful later. -Promotion needs evidence. Turn recurring failures into regression checks, evaluate candidate changes against a preserved baseline, review permission changes separately, and keep a rollback path. Do not preserve private one-off detail as a global rule. See [Verified Improvement Loops](verified-improvement-loops.md). +Improvements should be proposed separately from the run that discovered them. Compare the current and proposed versions, review permission changes separately, and keep a rollback path. See [Verified Improvement Loops](verified-improvement-loops.md). ## Minimal Setup For A Repo @@ -74,25 +59,25 @@ Start with: 1. `README.md` that names the project and start paths. 2. project instructions with local conventions and checks. 3. one obvious verification command. -4. a mission brief template. +4. a short mission brief for bigger work. 5. a fixture, demo, or tiny example if other people need to try it. That is enough for many projects. Add CI, skills, MCP, and subagents when they remove real friction. -For a recurring workflow, add only the next useful layer: a versioned harness, a small state contract, one high-value eval, and a reviewed promotion path. A graph or ontology should earn its complexity. +For recurring work, add only the next useful piece: a reusable workflow, one high-value check, and a reviewed way to adopt or reject changes. A graph or ontology should earn its complexity. ## Failure Modes -- Treating Codex like a generic chatbot instead of an agentic operating system. -- Staying at a tiny-task abstraction level when the model could safely derive the harness. -- Spawning agents without an agentic harness topology. +- Treating Codex like a generic chatbot instead of giving it a clear outcome and useful environment. +- Staying at a tiny-task abstraction level when the model could safely derive more of the path. +- Splitting work across agents without clear ownership and integration. - Adding broad instructions that never get used. -- Giving tool access without source-of-truth clarity. +- Giving tool access without a clear source of truth and permission boundary. - Verifying with a command unrelated to the change. - Capturing every session note as permanent memory. - Calling repeated automation "compounding" when no verified improvement changes future runs. -- Letting a system modify its active harness without a separate candidate, promotion gate, and rollback path. +- Letting a system modify its active workflow without a separate candidate, approval gate, and rollback path. ## Verification -The operating system is working when a new task starts with less explanation, touches fewer unrelated files, and finishes with better proof. It is compounding when a verified lesson safely improves the next comparable run. +The operating system is working when a new task starts with less explanation, touches fewer unrelated files, and finishes with better evidence. It is compounding when a verified lesson safely improves the next comparable run. diff --git a/guides/capability-lifecycle.md b/guides/capability-lifecycle.md index a282f1d..f6030fd 100644 --- a/guides/capability-lifecycle.md +++ b/guides/capability-lifecycle.md @@ -28,25 +28,11 @@ flowchart LR Do not report an installed capability as active, or a successful tool call as a verified outcome. -## From Verified Outcome To Promoted Capability +## Improving A Capability Is A Separate Decision -Outcome verification completes one run. It does not prove that the capability should change or expand. +Verifying one outcome does not prove that a capability should change, become easier to trigger, or gain more access. Treat any reusable change as a separate proposal: isolate it, compare it with the current version, review it, and keep a rollback path. -Use a separate promotion lifecycle: - -```mermaid -flowchart LR - A["Outcome evidence"] --> B["Change proposed"] - B --> C["Candidate isolated"] - C --> D["Regression evaluated"] - D --> E{"Promotion gate"} - E -->|pass| F["Promoted version"] - E -->|fail| G["Rejected with evidence"] - F --> H["Monitored use"] - H --> A -``` - -Permission, tool, connector, and data-access changes need their own review even when the behavior eval passes. A capability becoming more effective is not evidence that it should become more privileged or more visible. +Permission, tool, connector, and data-access changes need their own review even when the behavior eval passes. A capability becoming more effective is not evidence that it should become more privileged or more visible. See [Verified Improvement Loops](verified-improvement-loops.md) for the full change process. ## Progressive Disclosure @@ -86,7 +72,7 @@ Name the kind of profile whenever it matters. Do not assume that choosing a mode - Which can read data, write data, or trigger external side effects? - What evidence proves that activation improved the result? - Which capability descriptions overlap enough to create routing ambiguity? -- Which evals and evidence permit a new version to be promoted? +- Which evals and evidence permit a new version to be adopted? - Can the prior version be restored without reconstructing private state? ## Safe Public Examples diff --git a/guides/codexmaxxing-loop.md b/guides/codexmaxxing-loop.md index 7f25122..4ad05dc 100644 --- a/guides/codexmaxxing-loop.md +++ b/guides/codexmaxxing-loop.md @@ -1,8 +1,8 @@ # The Codexmaxxing Loop -Codex gets much more useful when the work is shaped into a loop instead of a wish. +Codex gets much more useful when the work has a clear outcome and a real check at the end. -At a low abstraction level, that loop can be a task. At a higher abstraction level, it can initialize a persistent harness or orchestration system. +Most work does not need a framework. Start with the simple loop, then make parts reusable only when the work is likely to happen again. The loop is simple: @@ -10,21 +10,20 @@ The loop is simple: 2. Define what success looks like. 3. Let Codex derive the approach. 4. Give it the right context and tools. -5. Check the real surface. -6. Propose the part that should help next time. -7. Promote it only after comparable verification. +5. Check the actual result. +6. Keep anything that will genuinely help next time. -## Three Nested Loops +## When The Work Repeats -The simple loop contains three different control cycles: +Recurring work adds two more questions: | Loop | Question | | --- | --- | -| Execution | Was the requested result produced? | -| Verification | Does evidence support the completion claim? | -| Evolution | Should anything about the harness change for future runs? | +| Do the work | Was the requested result produced? | +| Check the work | Does the evidence support that claim? | +| Improve the workflow | Should anything change for future runs? | -Keeping them separate prevents a task-local workaround from becoming a global rule and prevents the system from treating its own confidence as independent evidence. See [Verified Improvement Loops](verified-improvement-loops.md). +Keep those questions separate. A workaround that helped once should not quietly become a global rule, and the system's own confidence is not independent evidence. If the workflow is genuinely recurring, see [Verified Improvement Loops](verified-improvement-loops.md). ## Why It Matters @@ -32,7 +31,7 @@ Agentic work fails when it looks busy but does not move the real system. The loo ## Pattern -Treat every non-trivial request as an operating contract, but do not assume you have to handwrite the whole contract yourself. +For non-trivial work, make sure these questions have answers. You do not need to turn them into a form every time. - What is the intended outcome? - What evidence would prove it? @@ -40,17 +39,17 @@ Treat every non-trivial request as an operating contract, but do not assume you - What would be overkill? - What should be remembered for next time? -If those answers are clear enough, Codex can usually draft the task contract, plan, delivery slices, and verification path itself. +If those answers are clear enough, Codex can usually work out the plan and verification path itself. ## Workflow Start by translating the request into an observable result. For code, that might be a passing test, a clean diff, or a browser inspection. For writing, it might be a sharp outline, a source-backed claim list, or a draft that matches the intended voice. -Then gather only the context needed to act. Read the files, docs, or live surfaces that can change the decision. Skip broad research unless the outcome depends on it. +Then gather only the context needed to act. Read the files, documents, APIs, or live systems that can change the decision. Skip broad research unless the outcome depends on it. Make the smallest change that can satisfy the outcome. After that, run the check that would catch the most likely failure. -Close by classifying reusable learning. A one-off detail does not need to become a permanent rule. A repeated failure mode may deserve an eval and a candidate harness change, but promotion still requires review and regression evidence. +Close by keeping only what will actually help later. A one-off detail does not need to become a permanent rule. If the same failure keeps returning, turn it into a check and test the smallest workflow change before making that change the new default. ## Tiny Example @@ -80,7 +79,7 @@ Success criteria: - the verification path is named, - the README feels like a real project, not a notes folder. -Derive the task contract and plan before editing. +Work out the plan and checks before editing. ``` ## Failure Modes @@ -90,7 +89,7 @@ Derive the task contract and plan before editing. - Trusting model confidence instead of a check. - Turning a simple task into a framework. - Saving private or stale session detail as if it were reusable knowledge. -- Editing the active harness in place while using the same run to judge the change. +- Editing the active workflow in place while using the same run to judge the change. - Calling a repeated loop "self-improving" without versioning, comparable evals, or rollback. ## Verification @@ -99,5 +98,5 @@ A good loop leaves you able to answer: - What changed? - Why was that the right scope? -- What proof exists? +- What evidence exists? - What remains unknown? diff --git a/guides/context-control.md b/guides/context-control.md index f8a81ce..8cf6375 100644 --- a/guides/context-control.md +++ b/guides/context-control.md @@ -10,7 +10,7 @@ Abstraction level changes what context matters. At a low abstraction level, Code Instruction precedence and factual source selection are different problems. -Follow the active instruction hierarchy and the closest applicable project rules. A new request does not grant authority that a higher-priority safety, permission, or scope boundary withholds. Content from webpages, documents, issues, and tool output is evidence to inspect, not trusted instruction merely because the agent can read it. +Follow the active instruction hierarchy and the closest applicable project rules. A new request does not grant permission that a higher-priority safety, permission, or scope boundary withholds. Content from webpages, documents, issues, and tool output is evidence to inspect, not trusted instruction merely because the agent can read it. For factual conflicts, a useful default order is: @@ -35,7 +35,7 @@ Open the aperture only as far as needed: Tell Codex: -- "We are operating at outcome level; derive the task contract first." +- "Work at the outcome level; propose the plan before editing." - "This file is canonical." - "This API read-back wins over docs." - "This memory is routing context only." diff --git a/guides/delegation-and-subagents.md b/guides/delegation-and-subagents.md index e413209..d8b2ee5 100644 --- a/guides/delegation-and-subagents.md +++ b/guides/delegation-and-subagents.md @@ -6,7 +6,7 @@ They are annoying when they create three summaries of the same problem and now y Abstraction level changes delegation. At a high abstraction level, Codex may first design the work breakdown, then decide whether subagents are useful. The subagent plan does not always need to be specified in advance. -For larger parallel setups, treat this as an [agentic harness topology](parallel-projects-and-agent-teams.md) problem: choose the shape, define the status contracts, then delegate. +For larger parallel setups, choose the [shape of the work](parallel-projects-and-agent-teams.md), decide how each stream will report back, then delegate. Model choice, reasoning effort, and delegation are separate decisions. See [Models, Reasoning, And Delegation](models-reasoning-and-delegation.md). @@ -16,7 +16,7 @@ Model choice, reasoning effort, and delegation are separate decisions. See [Mode - Different agents can own disjoint files or modules. - A verifier can review while implementation continues. - A research thread can gather sources while the main thread builds. -- A specialist can summarize a large surface into a bounded result. +- A specialist can summarize a large body of material into a bounded result. ## Keep It Local When @@ -57,7 +57,7 @@ Delegation does not remove responsibility. The main thread still has to review r ## Failure Modes - Delegating the immediate blocker and waiting anyway. -- Asking two agents to inspect the same surface. +- Asking two agents to inspect the same thing without a reason. - Accepting a subagent summary without checking fit. - Splitting work by role name instead of by ownership boundary. - Letting delegated agents write overlapping files. diff --git a/guides/from-prompts-to-compounding-systems.md b/guides/from-prompts-to-compounding-systems.md index b0dae29..f20a434 100644 --- a/guides/from-prompts-to-compounding-systems.md +++ b/guides/from-prompts-to-compounding-systems.md @@ -1,55 +1,55 @@ # From Prompts To Compounding Systems -A prompt can describe a task. A durable Codex environment can embody how a class of tasks is understood, executed, checked, and improved. +A good prompt can get one job done. A good Codex setup can make a whole class of jobs easier to run, check, and improve. -The important transition is not simply from short prompts to long prompts, or from tasks to goals. It is from putting the operating method inside each prompt to engineering that method into inspectable, reusable system layers. +The shift is not from short prompts to long prompts, or even from tasks to goals. It is from explaining the method again in every prompt to putting the reusable parts into instructions, tools, workflows, and checks that Codex can find when it needs them. -> A prompt should increasingly become an initialization boundary for an already engineered system, not the place where the whole system is described. +> The prompt should start the system, not explain the whole system again. -## One Ladder Is Not Enough +## Three Questions -Agentic maturity has at least three independent dimensions: +Moving to a higher-level request is only one part of the picture: | Dimension | Governing question | Progression | | --- | --- | --- | -| Intent abstraction | How much implementation does the operator specify? | exact edit → framed task → outcome → system objective | -| System embodiment | Where does the operating method live? | prompt → template or skill → harness → orchestration graph → semantic system | -| Improvement closure | How does future performance improve? | ad hoc learning → captured lesson → trace and eval → reviewed change → gated self-improvement | +| What are you asking Codex to own? | How much of the implementation path is already specified? | exact edit → framed task → outcome → system objective | +| Where does the method live? | Is the method trapped in this prompt or reusable later? | prompt → template or skill → harness → workflow graph and shared schema | +| Does the learning improve the next run? | What happens when evidence shows a better way? | ad hoc lesson → captured check → evaluated change → reviewed adoption | -A high-level prompt does not prove that a mature system exists. It can still launch an opaque, disposable run. A mature system can accept a short prompt because its definitions, tools, state, checks, and authority boundaries already exist. +A high-level prompt can still launch an opaque, disposable run. A mature system can accept a short prompt because its definitions, tools, state, checks, and permission boundaries already exist. ## The Maturity Progression -| Stage | Unit Being Engineered | What Persists | Verification Target | +| Stage | What You Are Building | What Persists | What You Check | | --- | --- | --- | --- | | Instruction | one model action | little or nothing | requested output | -| Task contract | one bounded result | outcome, constraints, and proof path | task completion | -| Mission | a derived body of work | plan, context map, and delivery state | mission success criteria | -| Harness | a repeatable execution contract | instructions, tools, routing, outputs, and checks | repeatable behavior | -| Orchestration system | a graph of harnesses and state transitions | dependencies, ownership, state, and recovery paths | system invariants and end-to-end flow | -| Compounding system | a governed improvement loop | traces, evals, versioned changes, and promotion history | better future performance without regression | +| Bounded task | one result | outcome, constraints, and proof path | task completion | +| Mission | a body of work derived from a goal | plan, useful context, and delivery state | mission success criteria | +| Harness | the setup around a repeatable capability | instructions, tools, routing, outputs, and checks | repeatable behavior | +| Orchestration system | connected workflows and state changes | dependencies, ownership, state, and recovery paths | rules that must hold and the end-to-end flow | +| Compounding system | a controlled improvement loop | evidence, evals, versioned changes, and adoption history | better future performance without regression | -Higher maturity does not mean maximum autonomy. It means that more behavior is explicit, reusable, observable, and enforceable. Authority can remain narrow at every stage. +Higher maturity does not mean maximum autonomy. It means that more behavior is explicit, reusable, observable, and enforceable. Permissions can remain narrow at every stage. -## The Compounding Architecture +## What The Full System Can Look Like ```mermaid flowchart LR - A["Intent + policy"] --> B["Semantic contracts"] - B --> C["Orchestration graph"] + A["Intent + policy"] --> B["Shared vocabulary"] + B --> C["Workflow graph"] C --> D["Executable harnesses"] D --> E["Artifacts + state + traces"] E --> F["Verification + evals"] F --> G["Reviewed change set"] - G --> H["Versioned promotion"] + G --> H["Versioned adoption"] H --> C - I["Authority + privacy + provenance + rollback"] --- A + I["Permissions + privacy + sources + rollback"] --- A I --- C I --- F I --- H ``` -The model is only one component. The surrounding system determines what the model can see, which actions are possible, how intermediate state is represented, what counts as success, and whether a lesson changes future behavior. +The model is only one part. The surrounding setup determines what it can see and change, how work moves, what counts as success, and whether a useful lesson changes later runs. ## What Compounding Means @@ -61,8 +61,8 @@ Evidence of compounding includes: - feedback is linked to a particular behavior or system decision; - recurring failures become regression checks or evals; - proposed changes are versioned and attributable; -- candidate and promoted versions face comparable checks; -- promotion and rollback boundaries are explicit; +- the proposed and current versions face comparable checks; +- adoption and rollback boundaries are explicit; - successful improvements are reusable without repasting them into prompts; - private incidents are generalized before becoming shared guidance. @@ -70,24 +70,24 @@ Repeated automation without these properties may still be valuable, but it is no ## Build Depth-First -Do not begin with a universal graph, a large ontology, or an autonomous optimizer. +Do not begin with a universal graph, a large ontology, or an autonomous optimizer. Most workflows need none of those. Start with one recurring workflow: 1. Make its outcome and evidence explicit. -2. Capture the smallest repeatable harness. +2. Capture the smallest repeatable workflow. 3. Represent only the dependencies and state transitions that affect correctness. 4. Add an eval for one recurring or costly failure. -5. Require a reviewed, reversible change before promotion. -6. Expand only when another workflow can reuse the same contracts. +5. Require a reviewed, reversible change before adopting it. +6. Expand only when another workflow can reuse the same pieces. -The useful system is the smallest one that makes the next run more reliable. Complexity that does not improve legibility, verification, recovery, or reuse is coordination debt. +The useful system is the smallest one that makes the next run more reliable. Complexity that does not make the workflow easier to understand, check, recover, or reuse is coordination debt. ## Product Boundary Codex provides building blocks such as project instructions, skills, tools, hooks, subagents, chats, goals, and execution environments. A graph-oriented harness, ontology-driven workflow, or compounding improvement system is an architecture built with and around those primitives. It is not a single built-in Codex object. -Current OpenAI material supports the broader direction: skills package repeatable workflows, hooks run deterministic lifecycle scripts, subagents support bounded parallel work, and the agent improvement loop turns traces, feedback, evals, and reviewed harness changes into a reusable flywheel. OpenAI's harness-engineering account also emphasizes legible environments, enforceable invariants, feedback loops, and repository-local systems of record. +Current OpenAI material supports the broader direction: skills package repeatable workflows, hooks run deterministic lifecycle scripts, subagents support bounded parallel work, and the agent improvement loop connects traces, feedback, evals, and reviewed harness changes. OpenAI's harness-engineering account also emphasizes understandable environments, enforceable rules, feedback loops, and repository-local sources of truth. ## Sources diff --git a/guides/graph-and-ontology-engineered-harnesses.md b/guides/graph-and-ontology-engineered-harnesses.md index 802190d..9efb196 100644 --- a/guides/graph-and-ontology-engineered-harnesses.md +++ b/guides/graph-and-ontology-engineered-harnesses.md @@ -1,38 +1,38 @@ -# Graph And Ontology-Engineered Harnesses +# Workflow Graphs, Shared Vocabulary, And Harnesses -A reusable harness needs more than a good prompt. It needs an explicit contract for what exists, how work moves, which state can change, and how results are checked. +Most workflows do not need a graph or an ontology. Use them when the work has become hard to reason about in ordinary prose. -Graphs and ontologies make different parts of that contract legible. +A workflow graph helps when order, branching, retries, recovery, or handoffs affect the result. A shared vocabulary or schema helps when people, agents, or systems keep using the same words to mean different things. Both can sit inside a harness: the reusable setup around the model. -## Four Different Things +## Plain-English Version | Concept | Question It Answers | Typical Contents | | --- | --- | --- | -| Harness | What surrounds the model for this repeatable capability? | instructions, tools, routing, state, outputs, validation | -| Agent topology | Who performs the work? | parent, specialist, verifier, integrator | -| Orchestration graph | What depends on what, and how does execution move? | nodes, edges, gates, retries, handoffs, recovery | -| Ontology | What do the system's entities and relationships mean? | types, states, claims, provenance, invariants | +| Harness | What reusable setup surrounds the model? | instructions, tools, routing, state, outputs, checks | +| Team shape | Who performs each part? | parent, specialist, verifier, integrator | +| Workflow graph | What depends on what, and how does work move? | steps, connections, gates, retries, handoffs, recovery | +| Shared vocabulary or ontology | What do the important things, states, and relationships mean? | types, states, claims, sources, rules that must hold | -An agent team diagram is not automatically an orchestration graph. A data schema is not automatically an ontology. Use the smallest representation that removes real ambiguity. +An agent team diagram is not automatically a workflow graph. A data schema is not automatically an ontology. Use the smallest representation that removes a real source of confusion. -## Harness Contract +## What A Harness Needs To Make Clear -A harness should make these surfaces explicit: +A harness should make these things clear: -- **Intent:** outcome, policy, constraints, and authority. +- **Intent:** outcome, policy, constraints, and permissions. - **Inputs:** required sources, freshness expectations, and trust level. - **Capabilities:** instructions, skills, tools, models, and execution environment. - **Control flow:** routing, prerequisites, retries, escalation, and stop conditions. - **State:** durable, task-local, external, derived, and prohibited state. - **Outputs:** required artifacts, schemas, and unresolved-question handling. -- **Evidence:** traces, checks, evals, provenance, and completion language. -- **Change control:** version, proposed changes, promotion gate, and rollback path. +- **Evidence:** relevant events, checks, evals, sources, and completion language. +- **Change control:** version, proposed changes, adoption gate, and rollback path. -OpenAI's agent improvement loop similarly describes the harness as the full contract around the model, including instructions, tools, routing, output requirements, and validation checks. +OpenAI's agent improvement loop similarly describes the harness as the full setup around the model, including instructions, tools, routing, output requirements, and validation checks. -## The Orchestration Graph +## When A Workflow Graph Helps -Represent a workflow as a graph when order, branching, recovery, or ownership affects correctness. +Represent a workflow as a graph only when order, branching, recovery, or ownership affects correctness. Each node should declare: @@ -41,7 +41,7 @@ id: verify_sources purpose: Confirm that required sources are present and current reads: [source_manifest] writes: [source_verification] -authority: read_only +permissions: read_only preconditions: [source_manifest_exists] success: [all_required_sources_classified] failure_route: request_missing_source @@ -58,21 +58,21 @@ passes: [verified_source_refs] on_failure: request_missing_source ``` -The format is illustrative, not a Codex configuration syntax. The important property is that dependencies, state transfer, authority, evidence, and failure routing are inspectable. +The format is illustrative, not Codex configuration syntax. The point is to make dependencies, state transfer, permissions, evidence, and failure routes inspectable. -## The Ontology +## When A Shared Vocabulary Helps -Use an ontology when several harnesses must agree on meanings that prose alone keeps blurring. +Use a shared vocabulary when several workflows must agree on meanings that prose alone keeps blurring. If it formally defines entities, relationships, and rules, it may be useful to call it an ontology. A lightweight ontology can define: - entities such as `Mission`, `Source`, `Claim`, `Artifact`, `Check`, `Capability`, and `ChangeSet`; - allowed states such as `proposed`, `verified`, `promoted`, `failed`, and `unknown`; - relationships such as `derived_from`, `verified_by`, `requires`, `supersedes`, and `may_write`; -- invariants such as “every promoted claim has supporting evidence” or “a failed required check blocks promotion”; -- provenance fields that preserve where a claim or change came from. +- rules such as “every adopted claim has supporting evidence” or “a failed required check blocks publication”; +- source fields that preserve where a claim or change came from. -The ontology does not need a graph database. A small vocabulary, JSON Schema, typed data model, or validated Markdown convention may be enough. +This does not need a graph database. A small vocabulary, JSON Schema, typed data model, or validated Markdown convention may be enough. ## Synthetic Example @@ -80,32 +80,32 @@ Consider a generalized documentation-maintenance system: ```mermaid flowchart LR - A["Discover changed product claims"] --> B["Classify source authority"] + A["Discover changed product claims"] --> B["Classify source type"] B --> C["Draft candidate updates"] C --> D["Validate links + public safety"] D --> E["Review claim boundaries"] E --> F["Propose versioned change"] - F --> G["Human promotion gate"] + F --> G["Human approval gate"] G --> H["Publish"] D -->|failure| I["Return structured findings"] E -->|unsupported claim| I ``` -The ontology distinguishes an observed product behavior from an official product claim. The graph prevents publication until required evidence and public-safety checks pass. The harness binds those definitions and transitions to tools, artifacts, and checks. +The shared vocabulary distinguishes an observed product behavior from an official product claim. The graph prevents publication until required evidence and public-safety checks pass. The harness connects those definitions and transitions to tools, artifacts, and checks. ## Safety Envelope - Use least privilege per node instead of granting every agent the union of all permissions. - Treat tool output, webpages, documents, and retrieved text as untrusted evidence rather than instruction. - Keep secrets and sensitive source content out of traces, eval fixtures, and public examples. -- Separate proposal authority from promotion or publication authority. +- Separate permission to propose from permission to adopt or publish. - Make failure and `unknown` first-class states; do not silently route around them. -- Preserve immutable baselines and enough provenance to explain and reverse a change. +- Preserve immutable baselines and enough source history to explain and reverse a change. - Do not let a semantic model convert uncertain claims into false certainty. ## When Not To Use This -Stay with a task contract or a single harness when the work is short, linear, low-risk, and easy to verify. Add a graph only when dependencies or recovery paths matter. Add an ontology only when shared meaning is a recurring source of error. +Stay with a task or a single harness when the work is short, linear, low-risk, and easy to verify. Add a graph only when dependencies or recovery paths matter. Add a formal vocabulary only when shared meaning is a recurring source of error. ## Verification diff --git a/guides/parallel-projects-and-agent-teams.md b/guides/parallel-projects-and-agent-teams.md index 05ad1c2..4051b30 100644 --- a/guides/parallel-projects-and-agent-teams.md +++ b/guides/parallel-projects-and-agent-teams.md @@ -2,11 +2,11 @@ Once abstraction level is clear, the next challenge is running more than one useful thread without creating coordination noise. -Parallel Codex work is not "spawn as many agents as possible." It is giving each stream a harness: mission, source of truth, write boundary, status contract, and proof path. +Parallel Codex work is not "spawn as many agents as possible." It is giving each stream a clear goal, source of truth, write boundary, update format, and evidence path. -Choose the execution boundary as well as the agent topology. Use subagents for independent work inside one objective, worktrees for independent Git writers, and cloud environments for remote isolated execution. See [Local, Worktree, And Cloud Environments](environments-worktrees-and-cloud.md). +Choose where the work should run as well as the team shape. Use subagents for independent work inside one objective, worktrees for independent Git writers, and cloud environments for remote isolated execution. See [Local, Worktree, And Cloud Environments](environments-worktrees-and-cloud.md). -![Agentic harness topologies](../assets/agentic-harness-topologies.svg) +![Ways to structure parallel Codex work](../assets/agentic-harness-topologies.svg) ## The Simple Rule @@ -26,25 +26,25 @@ Bad splits: - three agents answering the same vague question, - one parent waiting on the delegated task that is actually the immediate blocker, - a swarm with no integration point, -- background work with no status contract. +- background work with no clear update format. -## Agentic Harness Topologies +## Useful Work Shapes -Topology is just the shape of the work system: who owns what, where state lives, how handoffs happen, and where proof comes back. +The shape is simply who owns what, where state lives, how handoffs happen, and where evidence comes back. -| Topology | Use It For | Watch Out For | +| Shape | Use It For | Watch Out For | | --- | --- | --- | -| Single-thread harness | small tasks, risky edits, tight judgment loops | fake speed from premature delegation | +| Single task | small tasks, risky edits, tight judgment loops | fake speed from premature delegation | | Hub-and-spoke | broad repo reviews, research plus implementation, multiple independent questions | parent must integrate and verify | | Pipeline | repeatable delivery flow: discover, implement, review, verify, publish | slow stages if each handoff is vague | | Portfolio board | multiple projects moving in parallel | stale state and invisible blockers | | Specialist team | recurring roles like researcher, implementer, verifier, release wrangler | role names are not enough; outputs must be concrete | -The topology can be manual at first. Once it repeats, make it a prompt, template, skill, custom agent, MCP workflow, or automation. +The setup can be manual at first. Once it repeats, make it a prompt, template, skill, custom agent, MCP workflow, or automation. -## Topology Is Not The Whole Graph +## The Team Is Not The Workflow -Agent topology describes who performs the work. An orchestration graph also describes: +The team shape describes who performs the work. A workflow graph also describes: - prerequisites and transition conditions, - state passed between nodes, @@ -53,11 +53,11 @@ Agent topology describes who performs the work. An orchestration graph also desc - retry, recovery, escalation, and stop paths, - evidence required before the next transition. -A hub-and-spoke team can run many different graphs. A single agent can also execute a multi-stage graph. Use [Graph And Ontology-Engineered Harnesses](graph-and-ontology-engineered-harnesses.md) when the control flow matters as much as the role split. +A hub-and-spoke team can run many different workflows. A single agent can also execute a multi-stage workflow. Use [Workflow Graphs, Shared Vocabulary, And Harnesses](graph-and-ontology-engineered-harnesses.md) when the order and failure routes matter as much as the role split. -## The Status Contract +## A Simple Update Format -Every parallel stream needs a small status shape. Otherwise you get a pile of summaries and no control surface. +Every parallel stream needs a small update shape. Otherwise you get a pile of summaries and no idea what is actually happening. ```markdown Mission: @@ -66,17 +66,17 @@ Source of truth: Allowed writes: Current state: Blocked on: -Touched surfaces: +What changed or was inspected: Evidence: Next handoff: Stop condition: ``` -This is the part that makes parallel projects feel less like juggling tabs and more like running a tiny operating system. +This is the part that makes parallel work feel less like juggling tabs and more like running one coherent job. ## Automating Delegation -For bigger work, Codex can propose the harness topology before execution instead of requiring every subtask to be designed manually. +For bigger work, Codex can propose the split before execution instead of requiring every subtask to be designed manually. ```markdown Goal: @@ -89,13 +89,13 @@ Constraints: Context: - + Before executing: -1. choose the right agentic harness topology, +1. choose the simplest useful work shape, 2. decide what should stay in the parent thread, 3. define any subagents, custom agents, or agent-team roles, -4. give each stream a source of truth, write boundary, status contract, and verification path, +4. give each stream a source of truth, write boundary, update format, and verification path, 5. identify the integration checkpoint. ``` @@ -112,9 +112,9 @@ Useful recurring roles: - implementer: owns a bounded file/module slice, - verifier: runs checks, screenshots, read-backs, or review passes, - docs/voice agent: keeps public docs clear and on-style, -- release wrangler: checks packaging, changelog, tags, CI, and public-readiness surfaces. +- release wrangler: checks packaging, changelog, tags, CI, and public-readiness requirements. -An agent team is not automatically smarter than one good loop. It becomes useful when each agent has a stable contract and the parent has a clean integration point. +An agent team is not automatically smarter than one good loop. It becomes useful when each agent has a clear responsibility and the parent has a clean integration point. ## Running Multiple Projects diff --git a/guides/projects-chats-goals-and-schedules.md b/guides/projects-chats-goals-and-schedules.md index 3eaa5f5..94de1f4 100644 --- a/guides/projects-chats-goals-and-schedules.md +++ b/guides/projects-chats-goals-and-schedules.md @@ -47,6 +47,8 @@ Use a scheduled task when time or recurrence is part of the requirement: Test the prompt manually first. Review the first few runs before trusting unattended behavior. +Recurrence alone does not make a workflow compounding. A schedule repeats the work; the workflow compounds only when evidence leads to a reviewed, testable improvement in later runs. + Local scheduled tasks need the computer and desktop app running when they depend on local files. In Git repositories, an isolated worktree can keep scheduled changes away from active work. Web scheduled tasks can use uploaded context and connected tools, but cannot directly operate on a folder on a local computer. The CLI can help prepare a workflow but does not provide the Scheduled management interface. ## Standalone Or Same-Chat Schedule diff --git a/guides/task-framing.md b/guides/task-framing.md index aa38797..86707a7 100644 --- a/guides/task-framing.md +++ b/guides/task-framing.md @@ -4,9 +4,9 @@ Good agent work starts with work that can be proven done. The goal is not to write a perfect prompt. It is to choose the right abstraction level. -Sometimes that means a tight task. Sometimes it means a broad goal with sharp success criteria, then asking Codex to write the task contract and delivery plan itself. +Sometimes that means a tight task. Sometimes it means a broad goal with sharp success criteria, then asking Codex to work out the plan itself. -## The Old Useful Frame +## A Useful Frame This is still useful for bounded tasks: @@ -18,7 +18,7 @@ Verification: Stop conditions: ``` -## The Higher-Abstraction Frame +## For Bigger Work For bigger work, use a goal-shaped frame: @@ -28,30 +28,30 @@ Success criteria: Constraints: Context: -First derive the task contract, source-of-truth map, delivery harness, and verification plan. Then execute. +First work out the plan, the sources that matter, and the verification path. Then execute. ``` -That small difference matters. The operator is not doing all the decomposition for Codex. The goal supplies enough context and discretion for Codex to propose the decomposition. +That small difference matters. The operator is not doing all the decomposition for Codex. The goal supplies enough context and discretion for Codex to propose the path. -## The System-Shaped Frame +## When A Reusable Workflow Already Exists -When a mature harness already exists, the prompt can be smaller because it initializes known layers instead of restating them: +When a mature reusable workflow already exists, the prompt can be smaller because it starts known layers instead of restating them: ```markdown Objective: -System or harness: +Workflow or harness: Inputs: -Authority: +Permissions: Evidence required: -Use the promoted contracts. Propose any reusable improvement separately from this run. +Use the current approved version. Propose any reusable improvement separately from this run. ``` -This only works when the referenced system is real, discoverable, and versioned. Naming an imaginary harness is not a substitute for engineering one. +This only works when the referenced workflow is real, discoverable, and versioned. Naming an imaginary system is not a substitute for building one. ## What To Include -Name the real surface. If the task is about production, say production. If it is about a local branch, say that. If a doc is canonical, name it. +Name the real target. If the task is about production, say production. If it is about a local branch, say that. If a document is authoritative, name it. Name the boundary. A good boundary prevents helpful-looking drift: no adjacent refactors, no new framework, no public release, no live write, or no auth changes. diff --git a/guides/team-adoption.md b/guides/team-adoption.md index 75e130b..6d7a0c3 100644 --- a/guides/team-adoption.md +++ b/guides/team-adoption.md @@ -58,11 +58,11 @@ The team changes how work enters, flows, gets reviewed, and gets measured becaus ### 6. Agentic operating system -The team can hand over broad goals with clear success criteria, and Codex can derive the project harness, delivery harness, work slices, and checks. +The team can hand over broad goals with clear success criteria, and Codex can work out the plan, work slices, tools, and checks. ### 7. Compounding system -Recurring workflows emit privacy-safe evidence, failures become regression checks, and reviewed harness changes improve later runs without silently expanding authority. Versions, promotion decisions, and rollback paths remain inspectable. +Recurring workflows produce privacy-safe evidence, failures become regression checks, and reviewed workflow changes improve later runs without silently expanding permission. Versions, adoption decisions, and rollback paths remain inspectable. ## What To Measure @@ -74,7 +74,7 @@ Recurring workflows emit privacy-safe evidence, failures become regression check - workflows converted into playbooks, - recurring failures converted into regression checks, - candidate changes rejected or rolled back before causing wider regression, -- performance of promoted versions against a stable baseline, +- performance of adopted versions against a stable baseline, - tasks that still require human-only judgment. ## Failure Modes @@ -84,7 +84,7 @@ Recurring workflows emit privacy-safe evidence, failures become regression check - Giving broad tool access without review gates. - Publishing internal examples without rewriting them. - Training people on prompts but not on verification. -- Automating self-modification before evaluation validity, authority, and rollback are trustworthy. +- Automating self-modification before the checks, permissions, and rollback path are trustworthy. ## Verification diff --git a/guides/thinking-abstraction-level.md b/guides/thinking-abstraction-level.md index 949f392..f345617 100644 --- a/guides/thinking-abstraction-level.md +++ b/guides/thinking-abstraction-level.md @@ -1,6 +1,6 @@ # Thinking Abstraction Level -Abstraction level is one of the most useful controls in agentic work. +Abstraction level is one of the most useful choices in agentic work: how much of the path are you giving Codex to work out? With older or weaker tooling, you had to drive close to the ground: exact prompts, exact steps, exact files, exact plan. That still works, but it leaves a lot of the value on the table. @@ -11,11 +11,11 @@ flowchart TD A["Tiny task"] --> B["Framed task"] B --> C["Outcome with success criteria"] C --> D["Broad goal with clear constraints"] - D --> E["Codex derives the project harness"] - E --> F["Codex executes and verifies"] + D --> E["Codex works out the path"] + E --> F["Codex executes and checks"] ``` -The human job shifts from "write every step" to "choose the right abstraction level." +The human job shifts from writing every step to choosing the right level and making the outcome clear. ## What Abstraction Level Means @@ -41,25 +41,25 @@ The automations broke after an upgrade. Diagnose the likely failure layer, make All three can be right. The useful judgment is knowing when Codex can take the higher-abstraction version and derive the work underneath it. -## Abstraction Is One Axis +## Abstraction Is Not The Whole System Abstraction level describes the request, not the maturity of the system receiving it. -Three independent dimensions matter: +Three separate questions matter: -| Dimension | Question | Progression | +| Question | What It Means | Progression | | --- | --- | --- | -| Intent abstraction | How much implementation is specified by the operator? | edit → task → outcome → system objective | -| System embodiment | Where does the operating method live? | prompt → reusable workflow → harness → orchestration system | -| Improvement closure | What changes future runs? | nothing → captured lesson → eval → governed promotion | +| What are you asking Codex to own? | How much of the implementation path is already specified? | edit → task → outcome → system objective | +| Where does the method live? | Is it in this prompt or in reusable instructions, tools, and checks? | prompt → reusable workflow → harness → orchestration system | +| Does the learning improve the next run? | What happens when the workflow finds a better way? | nothing → captured lesson → eval → reviewed change | -A broad prompt sent to a disposable agent is high in intent abstraction but low in system embodiment. A short request can initialize a mature system when its semantics, state, tools, checks, and authority boundaries already exist. +A broad prompt sent to a disposable agent is still a one-off run. A short request can start a mature system when the definitions, state, tools, checks, and permission boundaries already exist. See [From Prompts To Compounding Systems](from-prompts-to-compounding-systems.md) for the complete model. ## The New Default -For bigger work, do not start by writing the task contract yourself. +For bigger work, do not start by writing the whole plan yourself. Start with: @@ -77,17 +77,15 @@ Context: ``` -Then ask Codex to derive only the artifacts the work needs, such as: +Then ask Codex to work out only what the job needs, such as: -- the task contract, -- the source-of-truth map, -- the project harness, -- the agentic harness topology, -- the delivery harness, +- a short plan, +- the sources that matter, +- how the work should be split, - the verification plan, - the stop conditions. -That is the difference between using Codex as a task executor and using it as an agentic operating system. +For recurring work, those pieces may eventually become a reusable harness. For one-off work, they can stay as a small plan in the task. ## When To Go Higher @@ -113,12 +111,12 @@ Stay lower when: | --- | --- | --- | | Exact edit | File, line, change | The edit and maybe a quick check | | Framed task | Outcome, source, constraints | The steps and verification | -| Mission | Goal, success criteria, context | Task contract, plan, implementation, checks | -| System objective | Direction, policies, boundaries, invariants | Harness selection, orchestration, execution, evidence, change proposal | +| Mission | Goal, success criteria, context | Plan, implementation, and checks | +| System objective | Direction, policies, boundaries, rules that must hold | Reusable workflow, coordination, execution, evidence, and proposed improvements | A higher abstraction level does not mean less clarity. It means clarity moves from steps to outcomes, boundaries, and success criteria. -It also delegates more discretion. As abstraction rises, make scope, permissions, verification, and stop conditions more explicit. A broader goal never grants broader authority by itself. +It also delegates more discretion. As abstraction rises, make scope, permissions, verification, and stop conditions more explicit. A broader goal never grants broader permission by itself. ## The Failure Mode @@ -143,11 +141,11 @@ Success criteria: - validation still passes. ``` -Codex can turn that into a task contract, plan, file edits, and checks. +Codex can turn that into a sensible plan, file edits, and checks. ## Why This Matters -The ceiling moves when the model can reason well enough to design the harness. +The ceiling moves when the model can reason well enough to design more of the path. You stop spending all your energy decomposing work into tiny tickets and start spending more of it on: @@ -159,4 +157,4 @@ You stop spending all your energy decomposing work into tiny tickets and start s That is where Codex starts to feel less like autocomplete and more like a real operating layer for work. -The next ceiling is not a still-higher prompt. It is an environment in which a prompt initializes a versioned harness, verified evidence can improve future behavior, and authority remains explicit throughout the loop. +For work that repeats, the next ceiling is not a still-higher prompt. It is an environment where a short request starts a known workflow, evidence can improve later runs, and permission remains explicit throughout. diff --git a/guides/verification-before-completion.md b/guides/verification-before-completion.md index 914e79f..ba962b8 100644 --- a/guides/verification-before-completion.md +++ b/guides/verification-before-completion.md @@ -22,16 +22,16 @@ Use the smallest rung that proves the task: Higher is not always better. A live check can be overkill for a typo fix. A static check is too weak for a behavioral change. -## Verify The System As Well As The Output +## For Reusable Systems, Check More Than The Output -For a persistent harness or orchestration graph, task completion is only one claim. Also test: +For a persistent harness or workflow graph, task completion is only one claim. Also test: - required state transitions and failure routes; -- architecture, authority, and data-handling invariants; +- the rules that must hold across the architecture, permissions, and data handling; - recovery after interruption or partial failure; -- candidate behavior against the promoted baseline; +- the proposed version against the current baseline; - regression cases derived from prior failures; -- counter-metrics such as cost, latency, privilege growth, or data exposure. +- possible regressions such as cost, latency, broader permissions, or data exposure. Self-generated tests and agreement among agents can provide evidence, but they are not independent acceptance. Keep deterministic gates outside the model when a hard requirement can be checked mechanically, and use appropriately independent or human review for consequential judgment. @@ -51,7 +51,7 @@ Avoid unsupported claims like "should work" when a relevant check was available - Skipping verification because the change looks simple. - Claiming tests pass after a partial or failed run. - Forgetting to mention unavailable checks. -- Changing the harness and its evaluator together without preserving a comparable baseline. +- Changing the workflow and its evaluator together without preserving a comparable baseline. - Treating a generated eval as independent proof of the generator. ## Verification diff --git a/guides/verified-improvement-loops.md b/guides/verified-improvement-loops.md index 2987c72..0347545 100644 --- a/guides/verified-improvement-loops.md +++ b/guides/verified-improvement-loops.md @@ -1,20 +1,20 @@ # Verified Improvement Loops -A workflow does not improve merely because it remembers something. It improves when evidence from one run produces a controlled, testable change to future behavior. +A workflow does not improve merely because it remembers something. It improves when evidence from one run leads to a controlled, testable change in later runs. -That requires three distinct loops. +In plain language: keep the evidence, work out what actually failed, try the smallest change, and compare it with the current version before making it the new default. ## Three Loops | Loop | Purpose | Ends When | | --- | --- | --- | -| Execution loop | Produce the requested result | the candidate output exists | -| Verification loop | Test the result against the claim | required checks pass, fail, or remain explicitly unknown | -| Evolution loop | Improve the system that produced the result | a reviewed change is promoted or rejected with evidence | +| Do the work | Produce the requested result | the proposed output exists | +| Check the work | Test the result against the claim | required checks pass, fail, or remain explicitly unknown | +| Improve the workflow | Improve the system that produced the result | a reviewed change is adopted or rejected with evidence | Collapsing these loops creates predictable errors. The system starts changing itself before the original result is understood, treats self-review as independent proof, or promotes a local workaround into a global rule. -## The Evolution Loop +## The Improvement Loop ```mermaid flowchart LR @@ -24,29 +24,29 @@ flowchart LR D --> E["Failure classification"] E --> F["Candidate change"] F --> G["Regression evaluation"] - G --> H{"Promotion gate"} - H -->|promote| I["New harness version"] + G --> H{"Approval gate"} + H -->|adopt| I["New harness version"] H -->|reject| J["Preserved evidence"] I --> B ``` -## Evidence Packet +## Keep Enough Evidence Keep enough structured evidence to diagnose the system without preserving unnecessary sensitive content: - harness and policy version; - task class and synthetic or redacted case identifier; - declared inputs and source categories; -- tool and routing events relevant to the outcome; +- tool and routing events that affected the outcome; - produced artifacts and unresolved questions; - deterministic check results; - human or independent review findings; - failure classification; - proposed change and expected effect; -- candidate-versus-baseline evaluation result; -- promotion, rejection, or rollback decision. +- comparison between the proposed and current versions; +- adoption, rejection, or rollback decision. -Here, a trace means observable events and artifacts made available by the harness. It does not imply access to private model reasoning. Store raw prompts, credentials, private documents, personal data, and unrestricted traces only when there is a justified private retention policy. Public examples should use synthetic evidence. +Here, a trace means observable events and artifacts made available by the harness. It does not imply access to private model reasoning. Do not retain raw prompts, credentials, private documents, personal data, or unrestricted traces without a justified private retention policy. Public examples should use synthetic evidence. ## Diagnose Before Changing @@ -54,28 +54,28 @@ Classify failures before adjusting the system: | Failure Class | Likely Response | | --- | --- | -| Missing contract | clarify an instruction, schema, invariant, or required output | -| Contract not followed | improve enforcement, control flow, or tool affordance | +| Unclear expectation | clarify an instruction, schema, required rule, or output | +| Expectation not followed | improve enforcement, control flow, or tool use | | Missing capability | add or expose a narrowly scoped tool, skill, or source | -| Observability gap | capture the state needed to distinguish causes | +| Missing evidence | capture the state needed to distinguish causes | | Invalid eval | repair the scorer, fixture, or claim before optimizing | | Environmental failure | improve isolation, retry policy, or source availability | | One-off exception | preserve locally; do not generalize without repeated evidence | -Changing prompt wording is only one possible response. The higher-leverage fix may be a validator, a state contract, a routing rule, a clearer source boundary, or a better recovery path. +Changing the prompt is only one possible response. The better fix may be a validator, a clearer state shape, a routing rule, a better source boundary, or a recovery path. -## Promotion Protocol +## Adopting A Change 1. Freeze the current harness and evaluation baseline. 2. Turn the observed failure into a reproducible case when possible. 3. Define the intended change and the failure it should address. 4. Run the candidate against the existing suite and the new case. -5. Check counter-metrics for regressions, cost, latency, or privilege growth. -6. Review the diff and evidence at the required authority level. -7. Promote a new version or reject the candidate without rewriting history. +5. Check for regressions, extra cost or latency, broader permissions, and more data exposure. +6. Review the diff and evidence at the required approval level. +7. Adopt a new version or reject the candidate without rewriting history. 8. Monitor later runs and retain a rollback path. -A proposed change should not edit the active harness in place while it is being evaluated. Candidate and promoted state need distinct identities. +A proposed change should not edit the active harness in place while it is being evaluated. The current and proposed versions need distinct identities. ## Evaluation Boundaries @@ -95,7 +95,7 @@ Increase automation only as evidence and reversibility improve: 2. Propose a change set for review. 3. Implement a candidate in isolation and run evals. 4. Open a change for approval with evidence attached. -5. Auto-promote only narrow, reversible changes behind trusted gates. +5. Automatically adopt only narrow, reversible changes behind trusted gates. Do not use successful low-risk automation as blanket evidence that higher-impact changes can safely bypass review. @@ -103,17 +103,17 @@ Do not use successful low-risk automation as blanket evidence that higher-impact | Risk | Control | | --- | --- | -| Feedback poisoning | authenticate sources, preserve provenance, require review for policy changes | +| Feedback poisoning | authenticate sources, preserve where evidence came from, require review for policy changes | | Eval overfitting | use holdouts, counter-metrics, varied cases, and sample review | | Privilege expansion | diff capabilities and permissions separately from behavior changes | | Trace leakage | minimize collection, redact sensitive fields, separate public fixtures | | Self-confirmation | add independent checks at consequential boundaries | | Drift and pattern replication | run recurring invariant checks and retain a known-good baseline | -| Irreversible promotion | version changes, use staged rollout, and test rollback | +| Irreversible adoption | version changes, use staged rollout, and test rollback | ## Verification -An improvement loop is closed only when the evidence identifies what changed, why it should help, how it performed against the same contract, who or what authorized promotion, and how to reverse it. +An improvement loop is closed only when the evidence identifies what changed, why it should help, how it performed against the same expectations, who or what approved it, and how to reverse it. ## Sources diff --git a/resources/README.md b/resources/README.md index 2bdf51f..6e9fe6c 100644 --- a/resources/README.md +++ b/resources/README.md @@ -1,23 +1,23 @@ -# Copy-Paste Bits +# Copy-Paste Resources -Small reusable pieces for making Codex work less like "please vibe at this" and more like a useful operator. +Small reusable pieces for getting clearer, more reliable work out of Codex. ## Templates And Checklists - [Codex Operating Checklist](codex-operating-checklist.md) -- [Mission Brief Template](task-contract-template.md) +- [Mission Brief](task-contract-template.md) - [AGENTS.md Template](agents-md-template.md) - [Source Of Truth Map](source-of-truth-map.md) - [Workflow Audit Template](workflow-audit-template.md) - [Playground Prompts](playground-prompts.md) - [Compounding System Canvas](compounding-system-canvas.md) -- [Harness Graph Template](harness-graph-template.md) +- [Workflow Graph Template](harness-graph-template.md) - [Improvement Loop Checklist](improvement-loop-checklist.md) ## How To Use Them Copy the smallest thing that helps. Do not turn every tiny task into a paperwork exercise. -For bigger work, the move is usually: write the mission brief, then ask Codex to derive the task contract, source-of-truth map, delivery harness, and verification plan. +For bigger work, write a short mission brief and ask Codex to work out the plan, relevant sources, checks, and stop conditions. -Use the compounding-system resources only after a workflow repeats or several harnesses need shared state and meaning. A checklist is better than a graph when the work is still simple and linear. +Use the compounding-system resources only after a workflow repeats or several parts need shared state and language. A checklist is better than a graph when the work is still simple and linear. diff --git a/resources/agents-md-template.md b/resources/agents-md-template.md index 781b4c3..10dc20a 100644 --- a/resources/agents-md-template.md +++ b/resources/agents-md-template.md @@ -20,9 +20,9 @@ These instructions apply to this repository. Higher-level system and user instru ## Source Of Truth - Canonical docs: -- Runtime surface: +- Runtime environment: - Test or validation command: -- Deployment or release surface: +- Deployment or release target: ## Editing Rules diff --git a/resources/catalog.json b/resources/catalog.json index 1e59f38..0e93ee8 100644 --- a/resources/catalog.json +++ b/resources/catalog.json @@ -21,7 +21,7 @@ "status": "ready" }, { - "title": "Graph And Ontology-Engineered Harnesses", + "title": "Workflow Graphs, Shared Vocabulary, And Harnesses", "type": "guide", "path": "guides/graph-and-ontology-engineered-harnesses.md", "status": "ready" @@ -159,7 +159,7 @@ "status": "usable" }, { - "title": "Mission Brief Template", + "title": "Mission Brief", "type": "template", "path": "resources/task-contract-template.md", "status": "usable" @@ -195,7 +195,7 @@ "status": "usable" }, { - "title": "Harness Graph Template", + "title": "Workflow Graph Template", "type": "template", "path": "resources/harness-graph-template.md", "status": "usable" diff --git a/resources/codex-operating-checklist.md b/resources/codex-operating-checklist.md index aa82571..ebe4e8d 100644 --- a/resources/codex-operating-checklist.md +++ b/resources/codex-operating-checklist.md @@ -1,15 +1,25 @@ # Codex Operating Checklist -Use this before giving Codex a non-trivial mission. +Use the quick check for ordinary work. The rest is for larger, repeated, parallel, or higher-risk work; it is not paperwork that every task must complete. -## Abstraction Level +## Quick Check + +- What should be true when the work is done? +- Where should Codex look first? +- What may it change, and what is out of scope? +- What check is most likely to catch a plausible mistake? +- Does any action need separate approval? + +## Full Checklist For Bigger Or Repeated Work + +### Abstraction Level - The ask is at the right level: exact edit, task, outcome, or broad goal. - Success criteria are clearer than the step list. -- Codex can derive the task contract when the path is not obvious. -- Intent abstraction is not being confused with system maturity or autonomy. +- Codex can work out the plan when the path is not obvious. +- A broader request is not being confused with a more mature system or broader permission. -## Frame +### Frame - Outcome is stated as something observable. - Source of truth is named. @@ -17,71 +27,71 @@ Use this before giving Codex a non-trivial mission. - Allowed writes are clear. - Stop conditions are clear. -## Context +### Context - Current user instruction is captured. -- Relevant repo files, docs, or live surfaces are identified. +- Relevant repository files, documents, APIs, applications, or deployments are identified. - Volatile facts will be rechecked. - Old memory is treated as routing context unless verified. - Irrelevant adjacent work is out of scope. -## Tools +### Tools -- Required capabilities are available, enabled, and discoverable on the selected host. +- Required tools and capabilities are available, enabled, and discoverable on the selected host. - Reads happen before writes. - Secrets will not be printed or stored. - External writes have approval or a clear allowed boundary. - Codex has enough tool access to inspect before planning deeply. -## Environment +### Environment - Local, Worktree, or Cloud was chosen deliberately. - Parallel writers have isolated filesystems or non-overlapping ownership. - Local and remote runtime differences are explicit. - Source, merged, deployed, and released states will not be conflated. -## Permissions +### Permissions - The sandbox boundary is appropriate for the task. - Approval points are separate from filesystem and network access. - Browser, Computer Use, plugins, and MCP have their own reviewed boundaries. -- Higher abstraction or reasoning does not grant broader authority. +- Higher abstraction or reasoning does not grant broader permission. -## Parallel Work +### Parallel Work, If Needed -- The harness topology is named: single-thread, hub-and-spoke, pipeline, specialist team, or portfolio. +- The team shape is named: single task, hub-and-spoke, pipeline, specialist team, or portfolio. - Each agent or project stream has one owner and one source of truth. - Write boundaries do not overlap unless the parent owns integration. -- Every stream has a status contract and proof path. +- Every stream has a clear update format and evidence path. -## System Design +### Reusable System Design, If Needed -- The harness contract names instructions, tools, routing, state, outputs, and validation. -- Agent topology is distinguished from control flow and dependency edges. +- The harness names its instructions, tools, routing, state, outputs, and checks. +- The agent team is distinguished from workflow order and dependencies. - Shared entities, states, and relationships are defined only as deeply as recurring ambiguity requires. - Failure, error, incomplete, and unknown states have explicit routes. -- Every write and transition has an authority and evidence boundary. +- Every write and state change has a permission and evidence boundary. -## Verification +### Verification - The primary check is named before completion. - The check maps to the requested outcome. - Skipped checks will be reported. - The final answer will include what changed, what passed, and what remains. -## Output Surface +### Output Format -- The result belongs in chat, a repository file, an artifact, a visualization, or a Site. +- The result belongs in the task, a repository file, an artifact, a visualization, or a Site. - Visual files will be opened or rendered before completion. -- Deployment or publication has separate explicit authority. -- The chosen surface exists on the host where the work will run. +- Deployment or publication has separate explicit permission. +- The chosen format is supported on the host where the work will run. -## Learning +### Learning - Repeated lessons have a destination: instructions, template, script, skill, docs, or backlog. - One-off details are not promoted into durable rules. -- The execution, verification, and evolution loops are separate. +- Doing the work, checking it, and improving the workflow are separate. - Candidate changes are versioned and evaluated against a preserved baseline. - Permission and data-access changes receive separate review. -- Promotion and rollback authority are explicit. +- Permission to adopt or roll back a change is explicit. - Private evidence is generalized before becoming reusable guidance. diff --git a/resources/compounding-system-canvas.md b/resources/compounding-system-canvas.md index 33d856e..f04c4ee 100644 --- a/resources/compounding-system-canvas.md +++ b/resources/compounding-system-canvas.md @@ -1,24 +1,37 @@ # Compounding System Canvas -Use this for a recurring workflow that may deserve a persistent harness or orchestration system. Leave a field small or mark it `unknown` instead of inventing detail. +Use this for a recurring workflow that may deserve a reusable harness or coordinated system. Most workflows need only the quick version. Use the full canvas when risk, branching, shared state, or several agents and systems make the extra detail useful. + +## Quick Version + +```markdown +What keeps repeating? +What usually goes wrong? +What should be reusable next time? +What evidence would show an improvement? +What must stay under human approval? +What is the smallest useful change to try? +``` + +## Full Canvas ```markdown System objective: -Throughput or outcome unit: +What one successful run produces: System boundary: Explicit non-goals: -Intent and authority: +Intent and permissions: - Who can request a run? - What may the system read? - What may it write? - Which transitions require approval? -Semantic contract: -- Core entities: +Shared vocabulary or schema: +- Important things: - Important relationships: - Allowed states: -- Invariants: +- Rules that must always hold: - Meaning of failure, error, incomplete, and unknown: Harness: @@ -28,16 +41,16 @@ Harness: - Required outputs: - Validation checks: -Orchestration graph: +Workflow graph, only if needed: - Nodes: - Dependency and control-flow edges: - State passed between nodes: - Failure and recovery routes: - Integration point: -Evidence and observability: -- Required traces or events: -- Artifact provenance: +Evidence: +- Required events or records: +- Where artifacts and claims came from: - Deterministic checks: - Independent or human checks: - Data that must not be collected: @@ -45,14 +58,14 @@ Evidence and observability: Improvement loop: - Feedback sources: - Regression suite: -- Candidate-change process: -- Promotion gate: +- Proposed-change process: +- Adoption gate: - Rollback path: -- Counter-metrics: +- Possible regressions, costs, or new risks: Current constraint: Smallest useful next improvement: Evidence that would disconfirm it: ``` -The canvas describes an engineered pattern, not a native Codex configuration file. Start with one workflow and expand only when the contracts are reused. +The canvas describes an engineered pattern, not a native Codex configuration file. Start with one workflow and expand only when the pieces are genuinely reused. diff --git a/resources/harness-graph-template.md b/resources/harness-graph-template.md index 99ae209..359d6d3 100644 --- a/resources/harness-graph-template.md +++ b/resources/harness-graph-template.md @@ -1,8 +1,8 @@ -# Harness Graph Template +# Workflow Graph Template -Use this template when a workflow has meaningful dependencies, branching, state transitions, or recovery paths. +Use this advanced template when a workflow has meaningful dependencies, branching, state changes, or recovery paths. If the work is linear, use a checklist instead. -## Graph Contract +## Workflow ```markdown Graph name: @@ -10,13 +10,13 @@ Objective: Version: Entry condition: Completion condition: -Global invariants: +Rules that must always hold: Prohibited state or data: -Promotion authority: +Who can approve a new version: Rollback target: ``` -## Node Contract +## Step Repeat for each node: @@ -26,7 +26,7 @@ purpose: owner: reads: [] writes: [] -authority: +permissions: preconditions: [] success_conditions: [] evidence: [] @@ -34,7 +34,7 @@ timeout_or_budget: failure_route: ``` -## Edge Contract +## Connection Repeat for each edge: @@ -51,9 +51,9 @@ on_failure: - Does every write have one accountable owner? - Does every transition rely on observable evidence? - Can failures, errors, incomplete results, and unknowns remain visible? -- Are authority and data exposure narrower than the union of all nodes? +- Are permissions and data exposure narrower than the union of all steps? - Can the graph resume safely after interruption? -- Can a candidate graph be evaluated without replacing the promoted graph? +- Can a proposed graph be evaluated without replacing the current graph? - Is a graph actually needed, or would a linear checklist be clearer? -The YAML fragments are illustrative contracts, not built-in Codex syntax. +The YAML fragments are an illustrative format, not built-in Codex syntax. diff --git a/resources/improvement-loop-checklist.md b/resources/improvement-loop-checklist.md index 802bcb9..3ea397d 100644 --- a/resources/improvement-loop-checklist.md +++ b/resources/improvement-loop-checklist.md @@ -1,46 +1,58 @@ # Improvement Loop Checklist -Use this before allowing evidence from one run to change future system behavior. +Use this before allowing evidence from one run to change future behavior. + +## Quick Check + +For a small, low-risk workflow change, answer five questions: + +- [ ] What evidence shows the current workflow has a real problem? +- [ ] Does the proposed change address that problem rather than merely rewording the prompt? +- [ ] Was it compared with the current version using the same important checks? +- [ ] Could it broaden permissions, collect more data, or make another result worse? +- [ ] Can it be reviewed and rolled back? + +Use the full checklist below when the workflow is higher-risk, widely shared, or allowed to act with limited supervision. ## Baseline - [ ] The current harness or workflow has a versioned identity. - [ ] The intended outcome and evaluation claim are explicit. - [ ] The current eval suite and known limitations are preserved. -- [ ] Required authority and privacy boundaries are documented. +- [ ] Required permission and privacy boundaries are documented. ## Evidence - [ ] The failure or opportunity is supported by a trace, artifact, check, or review. - [ ] Sensitive inputs are excluded, minimized, or protected under an explicit retention policy. -- [ ] Evidence provenance is retained. +- [ ] The source of the evidence is retained. - [ ] `FAIL`, `ERROR`, `INCOMPLETE`, and `unknown` are not collapsed into success. ## Diagnosis -- [ ] The finding is classified as contract, enforcement, capability, observability, eval, environment, or one-off failure. +- [ ] The finding is classified as unclear expectation, enforcement, missing capability, missing evidence, invalid eval, environment, or one-off failure. - [ ] The proposed change addresses the evidenced cause rather than only its wording. -- [ ] A counter-hypothesis or disconfirming check has been considered. +- [ ] Another plausible explanation or disconfirming check has been considered. - [ ] A private incident has been generalized before becoming reusable guidance. -## Candidate +## Proposed Version -- [ ] The candidate is isolated from the promoted harness. +- [ ] The proposed version is isolated from the current harness. - [ ] The change is attributable and reviewable. - [ ] Existing regression cases and the new case are run comparably. -- [ ] Counter-metrics cover quality, cost, latency, privilege, and data exposure where relevant. +- [ ] Checks cover quality, cost, latency, permissions, and data exposure where relevant. - [ ] Generated tests are not treated as independent acceptance. -## Promotion +## Adoption - [ ] Required deterministic gates pass. - [ ] Consequential subjective claims receive human or appropriately independent review. - [ ] Permission, tool, and data-access changes are reviewed separately. -- [ ] Promotion authority is explicit. +- [ ] Permission to adopt the change is explicit. - [ ] A rollback path is tested or credibly available. -- [ ] Rejected candidates and failed evidence remain visible. +- [ ] Rejected versions and failed evidence remain visible. -## After Promotion +## After Adoption - [ ] Later runs are monitored for regression or drift. - [ ] The change is reusable without repasting private context. diff --git a/resources/playground-prompts.md b/resources/playground-prompts.md index fb65655..769a009 100644 --- a/resources/playground-prompts.md +++ b/resources/playground-prompts.md @@ -10,18 +10,10 @@ Help me turn this into a Codex-ready mission. What I want: -Ask me only the questions that would materially change the work. Otherwise make reasonable assumptions and give me: -- abstraction level -- goal -- success criteria -- constraints -- source-of-truth map -- delivery harness -- verification plan -- stop conditions +Ask me only the questions that would materially change the work. Otherwise make reasonable assumptions and give me a clear outcome, boundaries, plan, checks, and stop conditions. ``` -## Start High, Then Derive The Harness +## Start High, Then Let Codex Plan ```markdown Goal: @@ -36,14 +28,7 @@ Constraints: Context: -Before editing, choose the appropriate abstraction level and derive only what the work needs: -- task contract -- source-of-truth map -- project harness -- agentic harness topology -- delivery harness -- verification plan -- stop conditions +Before editing, work out only what the job needs: the plan, the sources that matter, the checks, and any stop conditions. If the work is likely to repeat, point out anything worth making reusable. ``` ## Run Parallel Projects Without Losing The Plot @@ -61,11 +46,11 @@ Success criteria: Constraints: -Design an agentic harness topology for this. Include: +Recommend a sensible way to divide the work. Include: - which work should stay serial, - which streams can run in parallel, - subagent or custom-agent roles, -- a status contract for each stream, +- a simple update format for each stream, - integration checkpoints, - verification for each stream, - what should become an automation, skill, or reusable agent later. @@ -137,22 +122,14 @@ Include: ## Turn A Repeated Workflow Into A Compounding System ```markdown -Recurring workflow: - - -Current failure or constraint: - - -Design the smallest system that can make later runs more reliable. Include: -- the harness contract, -- the minimum state and semantic model, -- the execution graph only if order, branching, or recovery matters, -- the evidence packet, -- one regression eval, -- candidate-versus-promoted version handling, -- promotion and rollback gates, -- counter-metrics, -- privacy, privilege, and feedback-poisoning risks. - -Distinguish native Codex capabilities from architecture built around them. Keep the design general and synthetic. Do not implement autonomous self-modification or broaden tool authority without separate approval. +I do this workflow regularly and the same problem keeps coming back: + + +Review the current approach and help me turn the useful parts into the smallest reusable system that will make later runs more reliable. + +Tell me what should stay in the prompt, what belongs in instructions, a skill, a script, or a check, and where human approval still matters. Add a workflow graph or shared schema only if order, branching, recovery, or inconsistent language is causing a real problem. + +Turn the recurring failure into a regression case. Compare any proposed workflow change with the current version before adopting it, keep a rollback path, and check for privacy, broader permissions, bad feedback, and self-confirming tests. + +Distinguish native Codex capabilities from architecture built around them. Keep the design general and synthetic. Do not implement autonomous self-modification or broaden tool permissions without separate approval. ``` diff --git a/resources/task-contract-template.md b/resources/task-contract-template.md index 93ad633..c9d831b 100644 --- a/resources/task-contract-template.md +++ b/resources/task-contract-template.md @@ -1,4 +1,4 @@ -# Mission Brief Template +# Mission Brief Use this when the goal is bigger than a single task and you want Codex to design the plan underneath it. @@ -8,12 +8,11 @@ Success criteria: Constraints: Context: -Ask Codex to derive: -- task contract -- source-of-truth map -- delivery harness -- verification plan -- stop conditions +Ask Codex to work out: +- a short plan +- the sources that matter +- the checks +- the stop conditions ``` ## Notes @@ -22,7 +21,7 @@ Ask Codex to derive: - `Success criteria` should describe what would make the result good. - `Constraints` should name scope, safety, privacy, compatibility, style, or time boundaries. - `Context` should point Codex at the first useful sources, not paste every possible thing. -- The derived contract is Codex's first output, not something you always need to write by hand. +- The plan is Codex's first output, not something you always need to write by hand. ## Example @@ -47,5 +46,5 @@ Constraints: Context: Start with README, guides, resources, and examples. -Ask Codex to derive the task contract, source-of-truth map, delivery harness, verification plan, and stop conditions before editing. +Ask Codex to work out the plan, relevant sources, checks, and stop conditions before editing. ``` diff --git a/resources/workflow-audit-template.md b/resources/workflow-audit-template.md index 3f2f048..55c9bba 100644 --- a/resources/workflow-audit-template.md +++ b/resources/workflow-audit-template.md @@ -23,13 +23,14 @@ Human approval gates: Current verification: Better verification: -Candidate Codex pattern: +Smallest useful Codex pattern: - assisted task - verified task - tool-connected workflow - repeatable playbook - operating redesign - agentic operating system +- compounding system with a verified improvement loop Reusable artifacts to create: diff --git a/scripts/validate_content.py b/scripts/validate_content.py index 12eb01d..86dfb6a 100755 --- a/scripts/validate_content.py +++ b/scripts/validate_content.py @@ -18,8 +18,6 @@ IGNORED_DIRS = {".git", ".venv", "__pycache__", "node_modules"} PUBLIC_TEXT_SUFFIXES = {".json", ".md", ".svg", ".toml", ".txt", ".yaml", ".yml"} -EDITORIAL_DIRS = {"docs", "guides"} -EDITORIAL_ROOT_FILES = {"CONTRIBUTING.md", "README.md", "SECURITY.md"} CATALOGED_DIRS = {"docs", "guides", "resources"} CATALOGED_EXTRA_FILES = {Path("examples/README.md")} KNOWN_CATALOG_TYPES = { @@ -112,10 +110,6 @@ LINK_PATTERN = re.compile(r"\[[^\]]+\]\(([^)]+)\)") URL_PATTERN = re.compile(r"https?://[^\s<>\"']+") ISO_DATE_PATTERN = re.compile(r"\b\d{4}-\d{2}-\d{2}\b") -FIRST_PERSON_PATTERN = re.compile( - r"(? None: ) -def without_fenced_code(text: str) -> str: - output: list[str] = [] - active_fence: str | None = None - for line in text.splitlines(): - match = FENCE_PATTERN.match(line) - if match: - marker = match.group(1)[0] - if active_fence is None: - active_fence = marker - elif active_fence == marker: - active_fence = None - continue - if active_fence is None: - output.append(line) - return "\n".join(output) - - -def validate_neutral_editorial_voice(root: Path, errors: list[str]) -> None: - for path in markdown_files(root): - rel_path = path.relative_to(root) - is_editorial = ( - path.name in EDITORIAL_ROOT_FILES - or (rel_path.parts and rel_path.parts[0] in EDITORIAL_DIRS) - ) - if not is_editorial: - continue - prose = without_fenced_code(path.read_text(encoding="utf-8")) - if FIRST_PERSON_PATTERN.search(prose): - errors.append( - f"{relative(path, root)} uses first-person editorial voice; " - "use neutral, generalized framing" - ) - - def normalize_url(raw_url: str) -> str: return raw_url.rstrip(".,;:!?)]}") @@ -666,7 +626,6 @@ def validate_repository(root: Path = ROOT) -> list[str]: validate_guide_headings(root, errors) validate_markdown_links(root, errors) validate_public_safety(root, errors) - validate_neutral_editorial_voice(root, errors) validate_external_urls(root, errors) validate_current_product_sources(root, errors) validate_asset_manifest(root, errors) diff --git a/tests/test_validate_content.py b/tests/test_validate_content.py index afad6aa..c8709c6 100644 --- a/tests/test_validate_content.py +++ b/tests/test_validate_content.py @@ -47,9 +47,13 @@ def test_action_references_require_full_commit_sha(self) -> None: ) self.assertFalse(validator.is_pinned_action_reference("actions/checkout@v5")) - def test_fenced_prompt_voice_is_excluded_from_editorial_prose(self) -> None: - text = "Neutral introduction.\n\n```text\nI want a synthetic example.\n```\n" - self.assertEqual(validator.without_fenced_code(text), "Neutral introduction.\n") + def test_first_person_editorial_voice_is_not_a_privacy_finding(self) -> None: + self.assertEqual( + validator.private_pattern_names( + "I think this pattern is useful, but the example should stay synthetic." + ), + [], + ) def test_svg_active_content_is_detected(self) -> None: self.assertEqual(