diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 8bb1be3..5abc377 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -4,12 +4,21 @@ on: push: pull_request: +permissions: + contents: read + jobs: content: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 + timeout-minutes: 10 steps: - - uses: actions/checkout@v5 - - uses: actions/setup-python@v6 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3.11" - - run: python3 scripts/validate_content.py + - name: Test validator safeguards + run: python3 -m unittest discover -s tests -v + - name: Validate public content + run: python3 scripts/validate_content.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb67a96..3027197 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,20 +9,31 @@ Thanks for improving Codexmaxxing. This repo is a public guide, so changes shoul - Improve templates, checklists, and source-of-truth maps. - Tighten safety guidance around tools, secrets, permissions, and verification. -## Keep It Public-Safe +## 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. Do not include: - real secrets, tokens, private keys, or `.env` files +- names, handles, personal project links, or biographical details - customer, employer, or private workspace details - raw session exports with private context - proprietary prompts or copied internal instructions -- machine-specific paths unless they are clearly generic examples +- machine-specific paths, hostnames, network details, account identifiers, or raw task IDs +- actual tool inventories, profiles, enabled integrations, hooks, rules, or security controls + +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. ## Validation Before opening a pull request, run: ```bash +python3 -m unittest discover -s tests -v python3 scripts/validate_content.py ``` + +The validator checks catalog coverage, local links, public-safe language and values, reviewed source hosts, current-product citations, asset review hashes, and the validation workflow's least-privilege policy. + +When adding or changing a visual asset, inspect the rendered result, remove embedded metadata, and update `assets/review-manifest.json` only after completing the recorded visual, privacy, and metadata checks. New external source hosts require an explicit review before they are added to the validator allowlist. diff --git a/README.md b/README.md index a9942b1..2177af0 100644 --- a/README.md +++ b/README.md @@ -2,22 +2,26 @@ Using Codex less like a chatbot and more like an agentic operating system. -Codexmaxxing is my field guide for getting real work done with Codex: apps, firmware, docs, ops, writing, research, repo cleanup, weird little side quests, and the occasional "why is this thing broken at 11pm?" investigation. +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 big unlock is altitude. With a strong enough model, the useful move is often not "write a better tiny task." It is "hold the goal at the right level, make success clear, and let Codex design the harness underneath it." +The central idea is abstraction level. The useful move is often not "write a better tiny task." It is "state the goal at the appropriate level, make success clear, and let Codex derive the work underneath it." + +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. + +> **Public alpha:** This is an independent, unofficial field guide, not an OpenAI product or a substitute for official documentation. The structure and examples are usable, but product-specific guidance may change as Codex evolves. No versioned release has been published. ![Codexmaxxing agentic operating system workbench](assets/codexmaxxing-hero.webp) ## Start Here -- [The Codexmaxxing Loop](guides/codexmaxxing-loop.md): the basic loop I keep coming back to. -- [Thinking Altitude](guides/thinking-altitude.md): the biggest unlock: giving Codex bigger goals at the right level. +- [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. - [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. -- [Parallel Projects And Agent Teams](guides/parallel-projects-and-agent-teams.md): how to run multiple threads without losing the plot. - [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. -- [Related Projects](docs/related-projects.md): real repos where these ideas show up. +- [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. ## The Shape Of It @@ -33,16 +37,16 @@ flowchart LR That loop works for code, but it is not just a coding thing. -I use the same pattern for: +The same pattern applies to: -- turning broad ideas into product-shaped side projects, +- turning broad ideas into product-shaped projects, - debugging live systems, - turning messy notes into useful docs, - researching gear or APIs, - shaping open-source repos, - reviewing UI, -- making tiny scripts that replace annoying repeated thinking, -- and generally moving more work out of my head and into a repeatable loop. +- making small scripts that replace repeated manual work, +- and turning recurring work into a repeatable loop. ## The Fun Part @@ -50,7 +54,7 @@ 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 waiting for me to handwrite every field, +- Codex can derive the task contract instead of requiring every field to be written in advance, - parallel projects have status contracts instead of vibes, - a tool call reads the live thing instead of guessing, - a test or screenshot catches the dumb mistake, @@ -59,31 +63,45 @@ The fun bit is when Codex stops being a novelty and starts becoming part of the This repo is a mix of notes, patterns, templates, and examples for that. -## Grab A Thing +## Choose The Surface | If you want to... | Start with | | --- | --- | -| think bigger without going vague | [Thinking Altitude](guides/thinking-altitude.md) | -| get better answers from Codex | [Task Framing For Agents](guides/task-framing.md) | -| stop context chaos | [Context Control](guides/context-control.md) | -| build a repeatable setup around a repo | [Build A Codex Operating System](guides/build-a-codex-operating-system.md) | -| run multiple projects or agents at once | [Parallel Projects And Agent Teams](guides/parallel-projects-and-agent-teams.md) | -| use tools, skills, and MCP without making a mess | [Tools, Skills, And MCP](guides/tools-skills-and-mcp.md) | -| split work across agents without making it worse | [Delegation And Subagents](guides/delegation-and-subagents.md) | -| bring this into a team | [Team Adoption](guides/team-adoption.md) | -| copy a template and go | [Copy-Paste Bits](resources/README.md) | -| see what this looks like in practice | [Example Missions](examples/README.md) | - -## Real-World-ish Examples - -- [Moodarr](https://github.com/jremick/moodarr): helps Plex + Seerr/Jellyseerr users find something to watch from moods, vibes, and loose natural-language ideas. -- [DragyDash](https://github.com/jremick/dragy-dash): turns Dragy Pro GNSS data into a live iPhone dashboard for speed runs, GPS quality, and session telemetry. -- [DragyDash ESP32](https://github.com/jremick/dragy-dash-esp32): puts Dragy Pro speed and GPS quality on a tiny LilyGO display so the useful telemetry is glanceable. -- [AI Workbench](https://github.com/jremick/ai-workbench): a workbench of reusable AI skills, prompts, harnesses, memory patterns, and agent workflow bits. -- [MySkills](https://github.com/jremick/myskills): a place to publish, review, discover, install, and use agent skills across web, API, CLI, and MCP. - -More notes on those are in [Related Projects](docs/related-projects.md). +| organize ongoing context, long-running work, or recurrence | [Projects, Chats, Goals, And Scheduled Tasks](guides/projects-chats-goals-and-schedules.md) | +| choose between the current checkout, isolated Git work, and remote execution | [Local, Worktree, And Cloud Environments](guides/environments-worktrees-and-cloud.md) | +| choose instructions, a script, skill, plugin, MCP connector, or schedule | [Skills, Plugins, MCP, And Tools](guides/skills-plugins-mcp-and-tools.md) | +| control a website or graphical application | [Browser, Computer Use, And Structured Connectors](guides/browser-computer-use-and-connectors.md) | +| select reasoning depth or parallel delegation | [Models, Reasoning, And Delegation](guides/models-reasoning-and-delegation.md) | +| split work without creating coordination debt | [Delegation And Subagents](guides/delegation-and-subagents.md) and [Parallel Projects And Agent Teams](guides/parallel-projects-and-agent-teams.md) | +| 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) | + +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. + +## Synthetic Work Patterns + +- Prepare an application repository so a contributor can run it without private infrastructure. +- 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. +- 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. + +## Current Status And Support + +Codexmaxxing is in public alpha. The durable operating patterns are intended for inspection, adaptation, and feedback; product-specific details are dated and should be checked against the cited official sources before use. + +Known limitations: + +- Codex surfaces 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. + +Use the repository's Issues tab for documentation defects, outdated guidance, or concrete improvement proposals. See [Contributing](CONTRIBUTING.md) for public-safe contribution expectations and [Security Policy](SECURITY.md) for private reporting guidance. No response time is guaranteed. ## License -[Apache License 2.0](LICENSE) - Copyright 2026 Jarel Remick. +[Apache License 2.0](LICENSE) diff --git a/SECURITY.md b/SECURITY.md index 99624ea..b36cd2e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,9 +4,7 @@ Codexmaxxing is a public guide and resource repo for Codex operating patterns. M ## Reporting -Use GitHub private vulnerability reporting when available: - - +Use the repository's **Security** tab and select **Report a vulnerability** when private vulnerability reporting is available. If that path is unavailable, open a minimal public issue asking for a private reporting channel. Do not include exploit details, credentials, tokens, private logs, customer data, or sensitive reproduction steps in public issues. diff --git a/assets/codexmaxxing-loop.svg b/assets/codexmaxxing-loop.svg index 8599bae..872c420 100644 --- a/assets/codexmaxxing-loop.svg +++ b/assets/codexmaxxing-loop.svg @@ -1,6 +1,6 @@ Codexmaxxing operating loop - A six-step Codexmaxxing workflow: set altitude, derive the harness, load tools and context, execute, verify, and capture the reusable pattern. + A six-step Codexmaxxing workflow: set abstraction level, derive the harness, load tools and context, execute, verify, and capture the reusable pattern. @@ -30,7 +30,7 @@ Codexmaxxing - Use Codex like an agentic operating system: clear altitude in, verified work out. + Use Codex like an agentic operating system: clear goals in, verified work out. goal -> harness -> proof @@ -52,11 +52,11 @@ 01 - HUMAN ALTITUDE + HUMAN ABSTRACTION LEVEL Set the mission Goal, success criteria, constraints, - and the altitude Codex should own. + and the abstraction level Codex should own. diff --git a/assets/review-manifest.json b/assets/review-manifest.json new file mode 100644 index 0000000..8bafd6c --- /dev/null +++ b/assets/review-manifest.json @@ -0,0 +1,31 @@ +{ + "version": "1.0.0", + "reviewed_on": "2026-08-20", + "assets": [ + { + "path": "assets/agentic-harness-topologies.svg", + "sha256": "0c560e4cc19b56bb80386056332b12c73960a6e5e714c31adf87561042d51256", + "checks": ["metadata", "privacy", "visual"] + }, + { + "path": "assets/codexmaxxing-hero.webp", + "sha256": "85c15076befa886c2bf7676ef28901a8d7cc22fc7caa756dd1df96951e66df49", + "checks": ["metadata", "privacy", "visual"] + }, + { + "path": "assets/codexmaxxing-loop.svg", + "sha256": "ca66bfac49c1fc4d4ea39953f33cf3c8d3389d2b268c6749e05ae4d08d59e098", + "checks": ["metadata", "privacy", "visual"] + }, + { + "path": "assets/social-preview.png", + "sha256": "5b619bdab66a558c175d3745ca3495fa6fa3e9ad9d6a3a0ee577d1fcda1a5a66", + "checks": ["metadata", "privacy", "visual"] + }, + { + "path": "assets/thinking-abstraction-level.svg", + "sha256": "9d06aa9d702511392c247e1a4f00406b4ccf0f739e7209a8dff84a81204d10ee", + "checks": ["metadata", "privacy", "visual"] + } + ] +} diff --git a/assets/social-preview.png b/assets/social-preview.png index 9c3017c..73041f2 100644 Binary files a/assets/social-preview.png and b/assets/social-preview.png differ diff --git a/assets/thinking-altitude.svg b/assets/thinking-abstraction-level.svg similarity index 89% rename from assets/thinking-altitude.svg rename to assets/thinking-abstraction-level.svg index 69f5cf7..b54017c 100644 --- a/assets/thinking-altitude.svg +++ b/assets/thinking-abstraction-level.svg @@ -1,5 +1,5 @@ - Thinking altitude ladder + Thinking Abstraction Level ladder A ladder showing movement from tiny tasks to broad goals where Codex derives the project and delivery harness. @@ -17,7 +17,7 @@ - Thinking Altitude + Thinking Abstraction Level The maxxing move is choosing the right level, then letting Codex design the path down. @@ -37,7 +37,7 @@ - More altitude does not mean less clarity. - It means clearer success criteria and better delegated planning. + Higher abstraction does not mean less clarity. + It means clearer success criteria, permission boundaries, and verification. diff --git a/docs/example-work-patterns.md b/docs/example-work-patterns.md new file mode 100644 index 0000000..027c2cc --- /dev/null +++ b/docs/example-work-patterns.md @@ -0,0 +1,76 @@ +# Example Work Patterns + +The examples on this page are synthetic. Their names, systems, paths, and evidence are fictional and do not describe a specific person, repository, organization, or environment. + +## Contributor-Ready Application + +A small application depends on services that contributors cannot access. The useful mission is not simply to improve its README. It is to create a safe local path that makes the project understandable and testable without private infrastructure. + +Useful outcomes might include: + +- fixture or demonstration data, +- a documented local run path, +- a single verification command, +- server-side secret handling, +- and a clear distinction between demonstration and production behavior. + +## Reusable Workflow Library + +A team repeats the same repository review and documentation workflow. Instead of preserving raw prompts or session logs, the reusable parts become a small skill, checklist, or validator. + +The public artifact should contain only the generalized workflow. It should not contain the originating repository, internal instructions, tool inventory, paths, configuration, or private examples. + +## Layered System Diagnosis + +A service reports a visible failure, but the cause could be access, runtime, integration, configuration, data, or presentation. + +The safe pattern is: + +1. start read-only, +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. + +## 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: + +```mermaid +flowchart LR + A["Source change"] --> B["Build"] + B --> C["Focused tests"] + C --> D["Simulator or fixture"] + D --> E["Physical target"] + E --> F["Observed result"] +``` + +The final claim should state exactly which surfaces were checked and which remain unverified. + +## Parallel Workstreams + +A broad review contains independent research, implementation, and verification questions. Parallel work is useful only when the lanes have non-overlapping ownership and a clear integration point. + +Each lane should define: + +- its source of truth, +- allowed writes, +- expected output, +- evidence, +- stop condition, +- and parent handoff. + +## Common Shape + +```mermaid +flowchart TD + A["High-level goal"] --> B["Success criteria"] + B --> C["Derived work plan"] + C --> D["Bounded execution"] + D --> E["Claim-specific check"] + E --> F["Reusable generalized pattern"] +``` + +The reusable pattern is the decision structure, not private detail from the work that produced it. diff --git a/docs/field-synthesis.md b/docs/field-synthesis.md index d0ff264..efcd74c 100644 --- a/docs/field-synthesis.md +++ b/docs/field-synthesis.md @@ -1,117 +1,113 @@ -# Field Notes +# Field Patterns -These are the patterns that keep showing up when I use Codex on actual work instead of toy prompts. +These generalized patterns recur across software, operations, devices, documentation, research, and non-code work. -The examples are generalized, but the shape is real: product repos, live systems, hardware, docs, research, and work that is not code at all. +The examples are synthetic and do not describe a specific person, repository, organization, or environment. -The biggest pattern is altitude. The more capable the model, the less I need to drive every step myself. I can give Codex a goal, success criteria, constraints, and context, then let it derive the project harness and delivery path. +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. ```mermaid flowchart TD - A["Human chooses altitude"] --> B["Goal + success criteria"] - B --> C["Codex derives contract"] - C --> D["Codex designs harness"] - D --> E["Codex executes"] + A["Choose abstraction level"] --> B["Goal + success criteria"] + B --> C["Derive work contract"] + C --> D["Design bounded approach"] + D --> E["Execute"] E --> F["Human or system verifies"] ``` ## Live Systems: Read First, Then Touch Things -The most useful Codex loop for ops work is boring in the best way: +A reliable operations loop is deliberately conservative: 1. prove which layer is failing, -2. avoid making random changes, +2. avoid unrelated changes, 3. make the smallest reversible move, -4. read the system back after. +4. read the system back afterward. ```mermaid flowchart LR - A["Symptom"] --> B["Network?"] + A["Symptom"] --> B["Access?"] B --> C["Host/runtime?"] - C --> D["App integration?"] - D --> E["Config/schema?"] - E --> F["Data or UI?"] + C --> D["Application integration?"] + D --> E["Configuration/schema?"] + E --> F["Data or presentation?"] F --> G["Small fix"] G --> H["Read-back"] ``` -This works for homelab stuff, production-ish apps, local containers, routers, media services, and all the little systems that lie to you in slightly different ways. +The pattern applies to deployed applications, local services, containers, devices, and other layered systems. Actual infrastructure details do not belong in a public example. -## Product Repos: Give People A Way To Play +## Product Repositories: Provide A Safe Trial Path -The best Codex-shaped product repos have a way to run without private infrastructure. +A contributor-ready repository should have a way to run without private infrastructure. -That usually means: +That often means: -- fixture mode, -- fake data, -- a local demo path, -- a single verification command, -- secrets that never leave the backend, -- and docs that explain the happy path before the architecture tour. +- fixture or demonstration data, +- a local run path, +- one clear verification command, +- secrets that remain outside the client and repository, +- and documentation that explains the happy path before the architecture tour. -[Moodarr](https://github.com/jremick/moodarr) is the cleanest example of this pattern right now. - -[AI Workbench](https://github.com/jremick/ai-workbench) and [MySkills](https://github.com/jremick/myskills) are the higher-altitude version of the same instinct: once useful workflows repeat, turn them into skills, harnesses, registries, and installation paths instead of treating them as one-off prompts. +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 -Running multiple Codex threads gets useful when each stream has a harness, not when everything becomes a background tab. +Parallel work becomes useful when each stream has a contract, not merely when more agents are running. -The pattern that holds up is: +The durable pattern is: - choose the topology, - split by ownership boundary, - give every stream a status contract, - keep the parent responsible for integration, -- verify each result before treating it as real progress. +- verify each result before treating it as progress. -That can be subagents inside one task, custom agents for recurring roles, or whole projects moving in parallel. The useful part is not the number of agents. It is the shape of the handoffs. +The useful part is not the number of agents. It is the shape of the handoffs. -## Hardware: The Board Gets A Vote +## Devices: The Real Target Gets A Vote -Firmware and device work is a useful antidote to agent overconfidence. +Device work is a useful antidote to agent overconfidence. -If the app talks to a phone, a BLE device, a display, or a board, then "the code looks right" is not enough. The loop has to reach the actual thing: +If software communicates with a phone, peripheral, display, or board, then "the code looks right" is not enough. Verification may need to reach the actual target: ```mermaid sequenceDiagram participant Codex - participant Repo + participant Repository participant Simulator participant Device - Codex->>Repo: make the smallest change - Repo->>Simulator: build and inspect + Codex->>Repository: make the smallest change + Repository->>Simulator: build and inspect Simulator-->>Codex: layout or test evidence Codex->>Device: install, flash, or launch - Device-->>Codex: runtime proof + Device-->>Codex: observed runtime evidence ``` -[DragyDash](https://github.com/jremick/dragy-dash) and [DragyDash ESP32](https://github.com/jremick/dragy-dash-esp32) are both examples of that loop. +The final report should distinguish source inspection, build evidence, simulation, and physical-device behavior. ## Non-Code Work Counts -Codex is also useful for things like: +The same operating loop can support: - shaping messy notes, - comparing options, -- planning a trip, -- writing a better update, +- drafting an update, - turning a vague idea into a concrete task, -- checking whether a decision is actually supported by evidence. +- checking whether a decision is supported by evidence. -The same rules apply. Name the outcome, load the right context, do the work, check the result. +Name the outcome, load only the necessary context, do the work, and check the result. ## The Pattern Underneath -Most Codex wins look like this: +Strong Codex workflows usually combine: -- right thinking altitude, -- better task shape, -- narrower context, -- real tool access, -- deterministic checks, -- reusable learning. +- an appropriate abstraction level, +- a clear task shape, +- narrow authoritative context, +- bounded tool access, +- claim-specific checks, +- reusable generalized learning. -When those pieces are missing, Codex is still impressive, but it is much more likely to produce confident sludge. +When those pieces are missing, fluent output can be mistaken for verified progress. diff --git a/docs/product-claim-boundaries.md b/docs/product-claim-boundaries.md new file mode 100644 index 0000000..27391d3 --- /dev/null +++ b/docs/product-claim-boundaries.md @@ -0,0 +1,44 @@ +# Product Claim Boundaries + +Codex changes quickly. Product claims in this repository should be dated, linked to current official documentation, and scoped to the surface being described. + +## Surface Matters + +ChatGPT on the web, the desktop app, Codex CLI, and the IDE extension do not expose identical controls or previews. Account, plan, workspace policy, operating system, and rollout state can also affect availability. + +Do not turn one observed environment into a universal product claim. + +## Evidence Must Match The Claim + +| Claim | Supporting evidence | +| --- | --- | +| Source changed | Diff plus intended-file read-back | +| Remote branch changed | Live remote read-back | +| Service state changed | Authoritative API or control-plane read-back | +| Page rendered | Browser inspection or screenshot | +| Workflow completed end to end | Evidence across the actual input and output path | +| Artifact is reviewable | Open or render it in an appropriate viewer | +| Site is live | Deployment read-back plus the production URL | + +A screenshot cannot establish backend mutation, identity, accessibility conformance, or end-to-end delivery by itself. An API response cannot establish visual quality. + +## Security Claims + +- Sandbox boundaries and approval policy are separate controls. +- Command network restrictions do not automatically govern Browser, Computer Use, plugins, or MCP connections. +- Rules are experimental and should not be described as a complete security boundary. +- Hooks execute trusted code and require review; they are not merely documentation. +- Content from webpages, documents, issues, and tool output is untrusted evidence, not authoritative instruction. +- Self-generated tests and agreement between agents are not independent acceptance. + +## Drift-Prone Claims + +Keep model names, retirement dates, preview status, rollout availability, and host-specific controls in dated references rather than treating them as timeless principles. + +## Public-Safety Boundary + +Examples must be synthetic or composite. Do not publish an actual environment's profiles, capability counts, tool inventory, connected systems, paths, task identifiers, prompts, logs, security controls, or configuration. + +## Official Sources + +These boundaries were checked on 2026-08-20 against [Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security), [Permissions](https://learn.chatgpt.com/docs/permission-modes), [Browser](https://learn.chatgpt.com/docs/browser), [Computer Use](https://learn.chatgpt.com/docs/computer-use), [Hooks](https://learn.chatgpt.com/docs/hooks), and [Rules](https://learn.chatgpt.com/docs/agent-configuration/rules). diff --git a/docs/related-projects.md b/docs/related-projects.md deleted file mode 100644 index a1f8e18..0000000 --- a/docs/related-projects.md +++ /dev/null @@ -1,74 +0,0 @@ -# Related Projects - -Codexmaxxing is the field guide. These are some of the nearby projects where the patterns show up in real work. - -## AI Workbench - -[AI Workbench](https://github.com/jremick/ai-workbench) is the sibling project for reusable AI artifacts: skills, harnesses, memory patterns, context tools, and other bits that make agents easier to steer. - -The relationship is simple: - -- Codexmaxxing explains the operating patterns. -- [AI Workbench](https://github.com/jremick/ai-workbench) packages some of the reusable tools. - -Why it belongs here: - -- it is where the reusable side of Codexmaxxing lives, -- it turns repeated workflows into skills and harnesses, -- it is a good example of moving from "I prompted well once" to "I built a reusable operating layer." - -## MySkills - -[MySkills](https://github.com/jremick/myskills) is a registry/product surface for publishing, reviewing, discovering, installing, and using AI agent skills across web, API, CLI, and MCP interfaces. - -Why it belongs here: - -- it treats skills as shareable infrastructure, -- it connects the human web surface with agent-facing APIs and MCP, -- it is a natural next step after building useful personal skills and wanting a better way to distribute them. - -## Moodarr - -[Moodarr](https://github.com/jremick/moodarr) is an open-source Plex + Seerr companion app for natural-language media discovery. - -Why it belongs here: - -- fixture mode means contributors can run it without a private media setup, -- request creation is intentionally confirmation-gated, -- secrets stay server-side, -- release checks include packaging and container smoke tests, -- the app is a good example of Codex helping shape a real product surface instead of just writing isolated code. - -## DragyDash - -[DragyDash](https://github.com/jremick/dragy-dash) is an experimental iOS dashboard for live Dragy Pro GNSS telemetry over Bluetooth LE. - -Why it belongs here: - -- Codex had to work across app code, BLE notes, simulator UI, physical-device install, and safety/privacy cleanup, -- the useful loop was not just "edit Swift", -- the real proof involved tests, simulator inspection, and phone/device behavior. - -## DragyDash ESP32 - -[DragyDash ESP32](https://github.com/jremick/dragy-dash-esp32) is firmware for showing Dragy Pro speed and GPS quality on a LilyGO T-Display-S3. - -Why it belongs here: - -- firmware makes verification brutally concrete, -- flashing, serial output, display behavior, and BLE runtime state all matter, -- it is a good reminder that an agent saying "this should work" is not the same as a board showing live data. - -## What These Have In Common - -```mermaid -flowchart TD - A["High-level goal"] --> B["Success criteria"] - B --> C["Codex designs harness"] - C --> D["Real project surface"] - D --> E["Execution"] - E --> F["Real check"] - F --> G["Reusable pattern"] -``` - -The pattern is portable: pick a real workflow, define success, give Codex the actual surface, verify the outcome, then save the bit that will help next time. diff --git a/docs/research-synthesis.md b/docs/research-synthesis.md index dfdfdf6..4cd79d0 100644 --- a/docs/research-synthesis.md +++ b/docs/research-synthesis.md @@ -2,27 +2,29 @@ This is the source-backed side of Codexmaxxing: what the current docs and agent research seem to agree on. +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. -The newer unlock is thinking altitude. Stronger models can often take a broad goal with clear success criteria and derive the task contract, project harness, delivery harness, and checks themselves. That changes what the human needs to be good at. +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. ## Sources Worth Reading Official OpenAI/Codex docs: -- [OpenAI Codex overview](https://openai.com/codex/) -- [Codex developer docs](https://developers.openai.com/codex/) -- [Codex CLI docs](https://developers.openai.com/codex/cli/) -- [Codex best practices](https://developers.openai.com/codex/learn/best-practices) -- [Codex cloud/web docs](https://developers.openai.com/codex/cloud) -- [Codex app review](https://developers.openai.com/codex/app/review) -- [Codex GitHub integration](https://developers.openai.com/codex/integrations/github) -- [AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md) -- [Codex skills](https://developers.openai.com/codex/skills/) -- [Codex MCP docs](https://developers.openai.com/codex/mcp/) -- [Codex subagents](https://developers.openai.com/codex/subagents/) -- [Codex automations](https://developers.openai.com/codex/automations/) -- [Codex use cases](https://developers.openai.com/codex/use-cases) +- [Current documentation index](https://learn.chatgpt.com/docs/llms.txt) +- [Projects and chats](https://learn.chatgpt.com/docs/projects) +- [Local, Worktree, and Cloud modes](https://learn.chatgpt.com/docs/environments/modes) +- [Goals and long-running work](https://learn.chatgpt.com/docs/long-running-work) +- [Scheduled tasks](https://learn.chatgpt.com/docs/automations) +- [Skills and plugins](https://learn.chatgpt.com/docs/skills-and-plugins) +- [MCP](https://learn.chatgpt.com/docs/extend/mcp) +- [Subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) +- [Browser](https://learn.chatgpt.com/docs/browser) and [Computer Use](https://learn.chatgpt.com/docs/computer-use) +- [Artifacts](https://learn.chatgpt.com/docs/artifacts-viewer), [Sites](https://learn.chatgpt.com/docs/sites), and [Visualizations](https://learn.chatgpt.com/docs/visualizations) +- [Models](https://learn.chatgpt.com/docs/models) +- [Permissions](https://learn.chatgpt.com/docs/permission-modes), [Rules](https://learn.chatgpt.com/docs/agent-configuration/rules), and [Hooks](https://learn.chatgpt.com/docs/hooks) +- [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) - [OpenAI Cookbook agent improvement loop](https://cookbook.openai.com/examples/agents_sdk/agent_improvement_loop) Broader agent/workflow references: @@ -31,7 +33,7 @@ Broader agent/workflow references: - [METR: Measuring AI ability to complete long tasks](https://metr.org/blog/2025-03-19-measuring-ai-ability-to-complete-long-tasks/) - [SWE-bench Verified](https://www.swebench.com/) -## What I Take From It +## What The Sources Suggest ### The Human Moves Up A Level @@ -46,7 +48,7 @@ That does not mean vague prompts work. It means high-level goals work when the s ### Codex Is A Work Surface -Codex is not just a box that answers questions. The current product surface spans local CLI work, cloud/web work, GitHub integration, code review, MCP tools, skills, automations, project instructions, and subagents. +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. That means the leverage is in the setup around the model: the repo, the tools, the docs, the task shape, and the checks. @@ -58,7 +60,7 @@ The common failure mode is feeding the agent a giant pile of "maybe relevant" in ### Tools Are Where Things Get Real -MCP and connectors let Codex do real work: inspect repos, read docs, open browsers, call APIs, use GitHub, query databases, and interact with systems. +Plugins, MCP, Browser, Computer Use, and other connectors let Codex inspect sources and interact with real systems. That is where the fun starts. It is also where bad assumptions become more expensive, so the tool story needs read-only exploration, write boundaries, and read-back. diff --git a/examples/README.md b/examples/README.md index 0e848ef..c295ddb 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,8 +1,10 @@ # Example Missions -Codexmaxxing makes more sense when it is attached to a real mission. +Codexmaxxing makes more sense when it is attached to a well-defined mission. -The point is not to pre-chew every task. Give Codex altitude, success criteria, and the right context. Let it design the plan underneath. +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. ## 0. Broad Goal: Let Codex Build The Harness @@ -14,7 +16,7 @@ Success criteria: - the README has a clear point of view, - the first-click paths are obvious, - examples include technical and non-technical work, -- related repos are linked, +- examples are synthetic and public-safe, - internal maintenance notes are not part of the public surface, - validation still passes. @@ -24,9 +26,9 @@ Constraints: - keep private details out. Context: -Start with README, docs, guides, resources, examples, and the related repos. +Start with README, docs, guides, resources, and examples. -Before editing, choose the right thinking altitude and derive the task contract, delivery harness, verification plan, and stop conditions. +Before editing, choose the appropriate abstraction level and derive only the task contract, delivery steps, verification plan, and stop conditions that the work needs. ``` Good for: repo shaping, product positioning, docs overhaul, public launch prep. @@ -34,7 +36,8 @@ Good for: repo shaping, product positioning, docs overhaul, public launch prep. ## 1. Product Repo: Make It Runnable ```markdown -This repo is nearly useful, but I want someone else to be able to run it without my private setup. +Goal: +Make this repository runnable by a new contributor without access to private infrastructure. Review the README, env examples, scripts, tests, and demo/fixture path. Find the smallest set of changes that would make the repo contributor-friendly. @@ -62,7 +65,7 @@ Start read-only. Separate possible causes by layer: Tell me what evidence would distinguish them, then gather the safe evidence first. ``` -Good for: homelab ops, deployed apps, integrations, "it worked yesterday" problems. +Good for: local services, deployed applications, integrations, and intermittent failures. ## 3. Hardware Loop: The Device Decides @@ -80,12 +83,12 @@ Verification path: 5. report exactly what was proven ``` -Good for: iOS, firmware, BLE, devices, dashboards, anything where the real target has opinions. +Good for: mobile applications, firmware, peripherals, devices, dashboards, and any workflow where the real target matters. ## 4. Non-Code Work: Make The Mess Useful ```markdown -I have messy notes and a rough goal: +Source notes and rough goal: Turn this into: @@ -102,7 +105,7 @@ Good for: writing, research, trip planning, comparison shopping, strategy notes, ## 5. Parallel Portfolio: Keep Multiple Threads Moving ```markdown -I have these active projects: +Active workstreams: - - - @@ -120,7 +123,69 @@ Success criteria: 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. ``` -Good for: side-project portfolios, multi-repo cleanup, launch prep, research plus implementation, and "I have five things open and somehow none of them are done." +Good for: small portfolios, multi-repository cleanup, launch preparation, and research paired with implementation. + +## 6. Choose The Execution Surface + +```markdown +Goal: +Complete these independent workstreams without overlapping writes: +- +- +- + +Before executing, decide which work belongs in: +- the parent chat, +- subagents, +- a separate worktree chat, +- a cloud task, +- a scheduled task. + +Explain the ownership, permission, integration, and verification boundary for each choice. Do not create parallel writers against the same files. +``` + +Good for: work that appears parallel but needs different execution environments. + +## 7. Choose The Capability Layer + +```markdown +Recurring workflow: + + +Decide whether the smallest durable solution is: +- project instructions, +- a checklist or template, +- a deterministic script, +- a skill, +- a plugin, +- an MCP connector, +- a scheduled task. + +Prefer the smallest layer that changes behavior reliably. Keep credentials, actual environment inventories, and private examples out of the artifact. +``` + +Good for: turning repeated work into a maintainable operating layer. + +## 8. Choose The Output Surface + +```markdown +Source material: + + +Desired use: + + +Choose between: +- a document, spreadsheet, presentation, or PDF, +- a static chart or diagram, +- an interactive visualization, +- a hosted Site, +- repository-native code. + +State the visual checks, deterministic checks, privacy boundary, and whether deployment is authorized. Do not deploy merely because creation is authorized. +``` + +Good for: artifact production, interactive explanations, dashboards, and hosted experiences. ## The Common Shape diff --git a/guides/README.md b/guides/README.md index 71195f3..43f84b6 100644 --- a/guides/README.md +++ b/guides/README.md @@ -1,11 +1,11 @@ # Guides -These are the longer notes. Not a course. Not a framework. More like: "here is the pattern I keep using because it keeps working." +These are practical operating notes rather than a course or a prescriptive framework. Each guide captures a reusable pattern and its limits. ## The Main Loop - [The Codexmaxxing Loop](codexmaxxing-loop.md) -- [Thinking Altitude](thinking-altitude.md) +- [Thinking Abstraction Level](thinking-abstraction-level.md) - [Task Framing For Agents](task-framing.md) - [Verification Before Completion](verification-before-completion.md) @@ -13,11 +13,23 @@ These are the longer notes. Not a course. Not a framework. More like: "here is t - [Build A Codex Operating System](build-a-codex-operating-system.md) - [Context Control](context-control.md) -- [Tools, Skills, And MCP](tools-skills-and-mcp.md) +- [Capability Lifecycle And Prompt Visibility](capability-lifecycle.md) +- [Skills, Plugins, MCP, And Tools](skills-plugins-mcp-and-tools.md) - [Parallel Projects And Agent Teams](parallel-projects-and-agent-teams.md) - [Delegation And Subagents](delegation-and-subagents.md) - [Team Adoption](team-adoption.md) +## Current Product Surfaces + +- [Projects, Chats, Goals, And Scheduled Tasks](projects-chats-goals-and-schedules.md) +- [Local, Worktree, And Cloud Environments](environments-worktrees-and-cloud.md) +- [Browser, Computer Use, And Structured Connectors](browser-computer-use-and-connectors.md) +- [Models, Reasoning, And Delegation](models-reasoning-and-delegation.md) +- [Permissions, Rules, Hooks, And Instructions](permissions-rules-and-hooks.md) +- [Artifacts, Sites, And Visualizations](artifacts-sites-and-visualizations.md) + +Current-product guides include a verification date and official sources. Read [Product Claim Boundaries](../docs/product-claim-boundaries.md) before turning host-specific behavior into a general claim. + ## How To Read These Pick the one that matches the kind of failure you are seeing. If Codex is wandering, read task framing. If it is confidently wrong, read context control. If it says it is done and you do not believe it, read verification. diff --git a/guides/artifacts-sites-and-visualizations.md b/guides/artifacts-sites-and-visualizations.md new file mode 100644 index 0000000..c588434 --- /dev/null +++ b/guides/artifacts-sites-and-visualizations.md @@ -0,0 +1,62 @@ +# Artifacts, Sites, And Visualizations + +Choose the output surface from how the result will be reviewed and used, not only from its source material. + +## Output Decision + +| Desired result | Use | +| --- | --- | +| Document, spreadsheet, presentation, or PDF | Artifact workflow with format-specific review. | +| Interactive chart, map, diagram, calculator, or simulation | Visualization, when available. | +| Hosted website, application, or game | Site. | +| Repository-native application | Ordinary code workflow, with browser or runtime verification as needed. | + +## Artifacts + +For file-producing tasks, state the expected file type, structure, source data, and review criteria. A generated file is not complete until it has been opened or rendered in an appropriate viewer. + +The desktop app can preview supported documents, presentations, spreadsheets, PDFs, and some HTML files. CLI and IDE workflows can create files but do not provide the same visual preview surface, so they should report output paths and the checks performed. + +## Visualizations + +Use a visualization when interaction materially improves understanding: + +- controls change the result, +- time or motion matters, +- spatial relationships matter, +- several variables need exploration. + +Prefer a normal table or static diagram when interactivity adds no value. Visualization rendering is not supported in Codex CLI or the IDE extension, and availability remains dependent on product rollout. + +## Sites + +Sites creates and hosts web experiences. Saving and deploying are different actions. + +Every Sites deployment URL is a production deployment. Save a version without deploying when review should happen before publication. The CLI can edit and test a compatible local project but does not provide the standalone Sites management view. + +Treat deployment as an external write. Verify the intended content, data boundary, authentication assumptions, and production URL after publication. + +## Review Contract + +```markdown +Output type: +Intended audience: +Required structure: +Source data: +Visual or interactive checks: +Privacy constraints: +Publication boundary: +Definition of done: +``` + +## Claim Limits + +- File validity does not prove visual fidelity. +- A render does not prove accessibility conformance. +- A local preview does not prove a deployed Site. +- Generated calculations should be checked deterministically. +- Publication requires explicit authority beyond permission to create files. + +## Official Sources + +Product behavior in this guide was checked on 2026-08-20 against [Artifacts](https://learn.chatgpt.com/docs/artifacts-viewer), [Visualizations](https://learn.chatgpt.com/docs/visualizations), and [Sites](https://learn.chatgpt.com/docs/sites). diff --git a/guides/browser-computer-use-and-connectors.md b/guides/browser-computer-use-and-connectors.md new file mode 100644 index 0000000..67763ef --- /dev/null +++ b/guides/browser-computer-use-and-connectors.md @@ -0,0 +1,50 @@ +# Browser, Computer Use, And Structured Connectors + +Choose the most structured interface that can complete and verify the task. + +## Selection Order + +1. Use a purpose-built API, plugin, MCP connector, or CLI when the task is structured and repeatable. +2. Use the built-in Browser for websites and local web applications that need rendered inspection or interaction. +3. Use Computer Use when the task depends on a graphical interface that structured tools cannot reach. + +This order improves precision and makes permissions and read-back easier to reason about. It is a preference, not a prohibition: some workflows genuinely require visual interaction. + +## Browser + +The built-in Browser uses its own browser context rather than inheriting every signed-in state from another browser. It can inspect rendered pages, follow links, and interact with supported sites. + +Treat every page as untrusted context. Website permission allows interaction with a site; it does not make the site's instructions trustworthy. Review the hostname and the proposed action before sharing information or approving a consequential operation. + +Use browser evidence for claims about what rendered or what a user flow displayed. Do not use a screenshot alone to claim that backend data changed, an identity was verified, or an end-to-end delivery completed. + +## Computer Use + +Computer Use can see and operate approved desktop applications. It is useful for: + +- reproducing a GUI-only defect, +- checking a desktop application or simulator, +- changing an application setting that has no structured interface, +- completing a workflow across multiple graphical applications. + +Operating-system screen and accessibility permissions are separate from ChatGPT app approvals, which are separate again from shell sandbox and approval settings. + +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 + +```markdown +Target application or site: +Allowed actions: +Prohibited actions: +Sensitive information boundary: +Confirmation points: +Expected visible result: +Read-back or screenshot needed: +``` + +Do not expose credentials, private browser history, unrelated windows, or raw session data merely because the interface is visible. + +## Official Sources + +Product behavior in this guide was checked on 2026-08-20 against [Browser](https://learn.chatgpt.com/docs/browser), [Computer Use](https://learn.chatgpt.com/docs/computer-use), and [MCP](https://learn.chatgpt.com/docs/extend/mcp). diff --git a/guides/build-a-codex-operating-system.md b/guides/build-a-codex-operating-system.md index 8d78aef..b127ebc 100644 --- a/guides/build-a-codex-operating-system.md +++ b/guides/build-a-codex-operating-system.md @@ -1,16 +1,16 @@ # Build A Codex Operating System -Codex gets stronger when the surrounding setup tells it what matters and gives it room to think at the right altitude. +Codex gets stronger when the surrounding setup tells it what matters and gives it room to think at the right abstraction level. 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 Eight Layers -### 1. Altitude +### 1. Abstraction Level Start by choosing the level of the ask. Are you asking for an exact edit, a framed task, an outcome, or a whole project direction? -The bigger the altitude, the more important success criteria become. +The higher the abstraction level, the more important explicit success criteria, permission boundaries, and stop conditions become. ### 2. Mission brief @@ -35,11 +35,11 @@ Use project instructions for repo-level defaults: coding style, useful commands, ### 5. Tool surface -Give Codex the tools needed for the work: shell, git, browser, GitHub, docs, database, or MCP servers. Start read-only when the state is uncertain. Allow writes only when the source of truth and rollback boundary are clear. +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). ### 6. Harness topology -Name the shape of the work. Is this a single-thread task, hub-and-spoke delegation, a delivery pipeline, a specialist agent team, or a portfolio of parallel projects? +Name the shape and environment of the work. Is this one chat, a subagent workflow, separate worktree chats, a delivery pipeline, or a set of cloud tasks? See [Local, Worktree, And Cloud Environments](environments-worktrees-and-cloud.md). Do not automate a topology you cannot explain. Each stream needs a source of truth, write boundary, status contract, and integration point. @@ -76,7 +76,7 @@ That is enough for many projects. Add CI, skills, MCP, and subagents when they r ## Failure Modes - Treating Codex like a generic chatbot instead of an agentic operating system. -- Staying at tiny-task altitude when the model could design the harness. +- Staying at a tiny-task abstraction level when the model could safely derive the harness. - Spawning agents without an agentic harness topology. - Adding broad instructions that never get used. - Giving tool access without source-of-truth clarity. diff --git a/guides/capability-lifecycle.md b/guides/capability-lifecycle.md new file mode 100644 index 0000000..3b15965 --- /dev/null +++ b/guides/capability-lifecycle.md @@ -0,0 +1,76 @@ +# Capability Lifecycle And Prompt Visibility + +Having a capability somewhere on disk is not the same as making it useful in a task. + +Use this lifecycle: + +```mermaid +flowchart LR + A["Available"] --> B["Installed"] + B --> C["Enabled"] + C --> D["Visible or retrievable"] + D --> E["Activated"] + E --> F["Used"] + F --> G["Outcome verified"] +``` + +## What Each State Means + +| State | Meaning | +| --- | --- | +| Available | The capability exists in a marketplace, package, repository, or local library. | +| Installed | Its files or connection are present in the current environment. | +| Enabled | The active host and profile allow it to load. | +| Visible or retrievable | Codex can discover it from prompt-visible metadata or a search route. | +| Activated | The current task explicitly selected it or matched its description. | +| Used | The workflow or tool actually ran. | +| Outcome verified | Evidence supports the result the capability was meant to produce. | + +Do not report an installed capability as active, or a successful tool call as a verified outcome. + +## Progressive Disclosure + +Skills use progressive disclosure. Codex initially sees compact metadata, then loads the full instructions when a skill is selected. A large skill library therefore needs clear names, descriptions, boundaries, and retrieval—not one enormous prompt containing every workflow. + +## Router Architecture + +A router is a local information architecture, not a special Codex product primitive. It can keep a small set of stable entry points visible while directing tasks to narrower skills only when needed. + +A generalized router might expose categories such as: + +- engineering delivery, +- research and writing, +- document and spreadsheet production, +- browser and computer interaction, +- connected systems, +- repository operations. + +The router should describe when to load a capability and when not to. It should not publish an originating environment's complete inventory, account state, provider configuration, or security controls. + +## Profiles Are Overloaded + +The word **profile** can refer to different things: + +- a model or configuration profile, +- a permission profile, +- an organizational ownership boundary such as personal or work. + +Name the kind of profile whenever it matters. Do not assume that choosing a model profile changes permissions, or that a permission profile changes which skills are visible. + +## Audit Questions + +- Which capabilities are meant to be visible by default? +- Which should be searchable but hidden from the initial prompt? +- Which require explicit invocation? +- Which are enabled only on a particular host or account? +- 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? + +## Safe Public Examples + +Public documentation should use generic capability categories and synthetic workflows. Do not publish actual inventories, counts, local paths, server names, enabled integrations, prompt dumps, hook definitions, rules, or authentication routes. + +## Official Sources + +Product behavior in this guide was checked on 2026-08-20 against [Build skills](https://learn.chatgpt.com/docs/build-skills), [Skills and plugins](https://learn.chatgpt.com/docs/skills-and-plugins), and [MCP](https://learn.chatgpt.com/docs/extend/mcp). Availability and host behavior can change. diff --git a/guides/codexmaxxing-loop.md b/guides/codexmaxxing-loop.md index 3fb89c1..68ebf6f 100644 --- a/guides/codexmaxxing-loop.md +++ b/guides/codexmaxxing-loop.md @@ -2,7 +2,7 @@ Codex gets much more useful when the work is shaped into a loop instead of a wish. -At small altitude, that loop can be a task. At higher altitude, it can be a whole project harness. +At a low abstraction level, that loop can be a task. At a higher abstraction level, it can be a whole project harness. The loop is simple: @@ -31,7 +31,7 @@ If those answers are clear enough, Codex can usually draft the task contract, pl ## Workflow -Start by translating the request into an observable result. For code, that might be a passing test, a clean diff, or a browser screenshot. For writing, it might be a sharp outline, a source-backed claim list, or a draft that actually sounds like you. +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. @@ -47,7 +47,7 @@ Bad shape: Make this repo better. ``` -Better shape, but still low-ish altitude: +Better shape, but still at a relatively low abstraction level: ```markdown Review this repo for the three highest-leverage changes that would make it easier for a new contributor to run locally. @@ -55,7 +55,7 @@ Review this repo for the three highest-leverage changes that would make it easie Do not edit yet. Check the README, package scripts, tests, and any fixture/demo path. Return a short plan with the exact files you would change and how you would verify it. ``` -Higher altitude: +Higher-abstraction version: ```markdown Make this repo easier for a new contributor to understand, run, and trust. diff --git a/guides/context-control.md b/guides/context-control.md index c8b2abb..f8a81ce 100644 --- a/guides/context-control.md +++ b/guides/context-control.md @@ -4,21 +4,23 @@ Context is not everything the agent can see. Useful context is the stuff that can change the decision. -Thinking altitude changes what context matters. At low altitude, Codex needs the exact file or command. At higher altitude, it needs the goal, constraints, examples of good work, tool access, and enough of the surrounding system to design a path. +Abstraction level changes what context matters. At a low abstraction level, Codex needs the exact file or command. At a higher abstraction level, it needs the goal, constraints, examples of good work, tool access, and enough of the surrounding system to design a path. -## Source Hierarchy +## Separate Instructions From Evidence -When sources conflict, choose deliberately. A good default order is: +Instruction precedence and factual source selection are different problems. -1. What you just asked for. -2. Success criteria and constraints. -3. Local project instructions. -4. Current repo files and tests. -5. Live read-backs when the task is about live state. -6. Official docs when current product behavior matters. -7. Prior memory and old notes. +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. -Prior memory is useful for routing and preferences, but live state and current docs win when the fact can drift. +For factual conflicts, a useful default order is: + +1. the source explicitly named as authoritative for the task, +2. current live read-backs when the claim concerns live state, +3. current repository implementation and tests for local behavior, +4. current official documentation for product behavior, +5. supporting notes and prior memory as background. + +Record exceptions instead of silently blending contradictory sources. Prior memory can help with routing, but live state and current documentation win when a fact can drift. ## Context Aperture @@ -53,3 +55,5 @@ Explicit context rules stop Codex from blending sources that should stay separat ## Verification Context control worked when the final answer can say which source decided the task and what evidence was checked. + +For installed capabilities and prompt visibility, continue with [Capability Lifecycle And Prompt Visibility](capability-lifecycle.md). diff --git a/guides/delegation-and-subagents.md b/guides/delegation-and-subagents.md index 381d99e..e413209 100644 --- a/guides/delegation-and-subagents.md +++ b/guides/delegation-and-subagents.md @@ -4,10 +4,12 @@ Subagents are great when the split is real. They are annoying when they create three summaries of the same problem and now you have to manage a tiny meeting. -Thinking altitude changes delegation. At high altitude, Codex may first design the work breakdown, then decide whether subagents are useful. You do not always need to specify the subagent plan up front. +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. +Model choice, reasoning effort, and delegation are separate decisions. See [Models, Reasoning, And Delegation](models-reasoning-and-delegation.md). + ## Delegate When - Independent questions can be answered in parallel. diff --git a/guides/environments-worktrees-and-cloud.md b/guides/environments-worktrees-and-cloud.md new file mode 100644 index 0000000..16cd461 --- /dev/null +++ b/guides/environments-worktrees-and-cloud.md @@ -0,0 +1,56 @@ +# Local, Worktree, And Cloud Environments + +Environment choice determines where files, commands, and state live. It is separate from model choice and separate from whether subagents are used. + +## Choose The Environment + +| Environment | Best fit | Main risk | +| --- | --- | --- | +| Local | Foreground work that should affect the selected project directory directly. | Changes can overlap with active human work. | +| Worktree | Parallel or background Git work that needs filesystem isolation. | Shared Git metadata and later integration still need care. | +| Cloud | Remote, reproducible, or longer-running work in an isolated configured environment. | The remote environment may differ from the local one. | + +Local and Worktree chats run on the computer or development environment containing the project. Cloud work runs remotely. + +## Worktrees Are Filesystem Isolation + +A worktree is another checkout of the same Git repository, not another type of agent. Worktrees share repository metadata while keeping file changes separate. + +Useful cases include: + +- independent writers working in parallel, +- background tasks that should not disturb the main checkout, +- scheduled Git work that needs isolation, +- comparing alternative implementations. + +Desktop-created worktrees normally begin at a detached `HEAD`. Review the diff and decide how the work should be integrated before treating it as merged. Handoff can move a chat and its code between Local and Worktree. + +## Cloud Is A Separate Runtime + +Cloud tasks run in isolated configured environments and can continue in parallel. Configure the dependencies, tools, variables, and setup steps the task actually needs. + +Review the resulting summary and diff before opening or merging a pull request. A successful cloud run does not prove that a different local or deployed environment behaves the same way. + +## Choosing Between Parallel Surfaces + +- Use subagents for bounded, independent reasoning or read-heavy work inside one objective. +- Use separate chats with worktrees for independent writers in the same Git repository. +- Use Cloud when work should run remotely or needs a reproducible configured environment. +- Use Local when tight foreground interaction with the current checkout matters most. + +## Verification + +Always label the state being reported: + +- local source, +- worktree source, +- remote branch, +- merged branch, +- deployed runtime, +- released artifact. + +One state does not imply the next. + +## Official Sources + +Product behavior in this guide was checked on 2026-08-20 against [environment modes](https://learn.chatgpt.com/docs/environments/modes), [Worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees), and [Codex cloud](https://learn.chatgpt.com/docs/cloud). diff --git a/guides/models-reasoning-and-delegation.md b/guides/models-reasoning-and-delegation.md new file mode 100644 index 0000000..afcf772 --- /dev/null +++ b/guides/models-reasoning-and-delegation.md @@ -0,0 +1,48 @@ +# Models, Reasoning, And Delegation + +Model choice, reasoning effort, and parallelism are separate controls. Use each because the task needs it, not because a higher setting sounds safer. + +## Start With The Task Shape + +| Task shape | Starting choice | +| --- | --- | +| Narrow, clear, repeatable | Faster model and default or lower reasoning. | +| Ambiguous, multi-step, tool-heavy | Strong general model and higher reasoning when needed. | +| Hard single problem where depth matters most | Max, when supported. | +| Complex work with meaningful independent parts | Ultra or explicit subagents, when supported. | + +Available models and controls vary by host, account, and rollout. Keep exact model names in dated references rather than turning them into permanent workflow rules. + +## Reasoning Effort + +Higher reasoning can improve planning and analysis, but it also takes longer and consumes more usage. Start with the default. Increase effort when the failure mode is shallow analysis, unresolved ambiguity, or a difficult integration decision. + +Do not use reasoning effort as a substitute for missing evidence, permissions, tools, or acceptance criteria. + +## Max And Ultra + +Max gives the selected model more time to reason about one task. Use it when depth matters more than speed or usage. + +Ultra goes beyond a single-agent run and uses subagents for separate parts of a complex task. Use it when the work has real parallel structure. Most tasks need neither. + +At other reasoning levels, request subagents explicitly when parallel work would materially improve speed, context handling, or review quality. + +## Subagent Boundaries + +Subagents are a good starting point for read-heavy work such as exploration, testing, triage, and summarization. Parallel write-heavy work creates more conflict and coordination overhead. + +Subagent workflows consume more tokens than a comparable single-agent run. The parent remains responsible for boundaries, integration, verification, and the final claim. + +When a subagent model or reasoning effort is not set explicitly, local Codex clients can inherit those settings from the parent. Do not assume every host follows the same configuration path. + +## Selection Questions + +- Is the task hard because it needs deeper reasoning or because it lacks context? +- Can independent work run without overlapping writes? +- Is the expected quality gain worth the additional time and usage? +- Can each delegated result be checked independently? +- Does one focused agent preserve important judgment better than a parallel split? + +## Official Sources + +Product behavior in this guide was checked on 2026-08-20 against [Models](https://learn.chatgpt.com/docs/models) and [Subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents). diff --git a/guides/parallel-projects-and-agent-teams.md b/guides/parallel-projects-and-agent-teams.md index 6b25a17..5a8d40a 100644 --- a/guides/parallel-projects-and-agent-teams.md +++ b/guides/parallel-projects-and-agent-teams.md @@ -1,9 +1,11 @@ # Parallel Projects And Agent Teams -The next unlock after thinking altitude is running more than one useful thread at once without turning your workspace into soup. +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. +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). + ![Agentic harness topologies](../assets/agentic-harness-topologies.svg) ## The Simple Rule @@ -61,7 +63,7 @@ This is the part that makes parallel projects feel less like juggling tabs and m ## Automating Delegation -For bigger work, I do not want to hand-design every subtask. I want Codex to propose the harness topology. +For bigger work, Codex can propose the harness topology before execution instead of requiring every subtask to be designed manually. ```markdown Goal: @@ -84,7 +86,7 @@ Before executing: 5. identify the integration checkpoint. ``` -Codex can usually design a better work breakdown than a tired human trying to pre-chew every task at midnight. +Codex can often propose a useful work breakdown when the goal, boundaries, and integration point are clear. ## Custom Agents And Agent Teams @@ -103,7 +105,7 @@ An agent team is not automatically smarter than one good loop. It becomes useful ## Running Multiple Projects -For parallel projects, keep a tiny board somewhere: Markdown, issues, Linear, Notion, GitHub Projects, a local JSON file, whatever actually survives contact with your day. +For parallel projects, keep a small durable board in an appropriate tracker or structured local file. Track only what changes decisions: @@ -115,7 +117,7 @@ Track only what changes decisions: - proof needed, - last verified date. -Do not make a giant PM system for weekend side quests. The point is to keep enough state that Codex can resume, delegate, and verify without you rehydrating the whole universe every time. +Do not create a large project-management system for a small portfolio. Keep enough state for Codex to resume, delegate, and verify without reconstructing the entire context every time. ## When To Stay Serial diff --git a/guides/permissions-rules-and-hooks.md b/guides/permissions-rules-and-hooks.md new file mode 100644 index 0000000..295d48c --- /dev/null +++ b/guides/permissions-rules-and-hooks.md @@ -0,0 +1,57 @@ +# Permissions, Rules, Hooks, And Instructions + +These controls operate at different layers. Combining them into one idea called "safety" creates false confidence. + +## Permission Layers + +- The **sandbox** defines which filesystem and network resources local commands can access. +- **Approvals** define when Codex pauses before an action or routes it for review. +- **App and connector approvals** govern tool calls outside ordinary shell execution. +- **Operating-system permissions** govern capabilities such as screen and accessibility access. + +Changing who reviews an approval does not expand the sandbox. Start with the narrowest mode that permits the task. + +## Project Instructions + +`AGENTS.md` supplies durable instructions. Codex builds an instruction chain from broader scope toward the current working directory, with closer project guidance taking precedence. + +Keep repository instructions short and public-safe. Put detailed procedures in guides, skills, or scripts. Treat changes to instruction files as behavior changes, not ordinary prose edits. + +## Rules + +Rules control how matching commands are handled outside the sandbox. Decisions can allow, prompt, or forbid an invocation, with the most restrictive matching decision winning. + +Rules are experimental. Test them with their supported checker and do not describe them as a complete security boundary. + +## Hooks + +Hooks run executable logic at lifecycle events. Multiple matching hooks can run, and some run concurrently. Non-managed hooks require review and trust; changed hook definitions require renewed review. + +Hooks can inspect or influence tool activity, but they also create code-execution and data-exposure risk. Avoid secrets in hook output and do not publish an actual environment's hook definitions. + +## What Each Layer Is Good At + +| Need | Prefer | +| --- | --- | +| Durable repository expectations | Project instructions | +| Filesystem and network boundary | Sandbox or permission profile | +| Human or automatic review point | Approval policy | +| Deterministic command decision | Rule | +| Lifecycle automation or policy check | Hook | +| Repeatable task workflow | Skill | + +## Safety Review + +Before enabling a new control: + +- identify who owns it, +- inspect its source, +- define the exact scope, +- test expected allow and deny cases, +- check what data it can read or emit, +- confirm how it fails, +- keep a recovery path. + +## Official Sources + +Product behavior in this guide was checked on 2026-08-20 against [Permissions](https://learn.chatgpt.com/docs/permission-modes), [Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security), [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md), [Rules](https://learn.chatgpt.com/docs/agent-configuration/rules), and [Hooks](https://learn.chatgpt.com/docs/hooks). diff --git a/guides/projects-chats-goals-and-schedules.md b/guides/projects-chats-goals-and-schedules.md new file mode 100644 index 0000000..3eaa5f5 --- /dev/null +++ b/guides/projects-chats-goals-and-schedules.md @@ -0,0 +1,68 @@ +# Projects, Chats, Goals, And Scheduled Tasks + +These surfaces organize different kinds of continuity. They should not be treated as interchangeable names for one agent run. + +## Core Terms + +| Surface | Use it for | +| --- | --- | +| Project | Related chats, files, instructions, and sources that should share context over time. | +| Chat | One conversation and execution history. Product interfaces and tools may also call it a task or thread. | +| Goal | A completion-oriented outcome inside one chat. | +| Scheduled task | A recurring or delayed invocation with its own cadence and run history. | + +Use a standalone chat for self-contained work. Use a project when several chats need the same sources or instructions. + +## Plan Before Goal + +Use planning when the outcome, constraints, or success criteria still need to be discovered. Start a goal when the result can be stated clearly enough for Codex to decide whether it is complete. + +```markdown +Outcome: + + +Constraints: + + +Definition of done: + +``` + +A goal does not broaden permissions. Keep steering and status questions in the same chat so the goal retains its context. + +## When To Use Separate Chats + +Use separate chats when workstreams are independent. Do not give two chats overlapping write access to the same source unless an explicit integration process owns the conflict risk. + +Related chats can stay in one project without sharing a single execution history. + +## Scheduled Tasks + +Use a scheduled task when time or recurrence is part of the requirement: + +- a one-time follow-up, +- a recurring review, +- a monitor with a stop condition, +- a skill-driven maintenance workflow. + +Test the prompt manually first. Review the first few runs before trusting unattended behavior. + +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 + +- Use a standalone scheduled task when each run should start independently. +- Schedule inside an existing chat when later runs need that chat's context. +- Put durable behavior in the saved prompt or an explicit skill rather than relying on incidental conversation history. + +## Safety Checks + +- Use the narrowest permissions that let an unattended run succeed. +- Prefer worktree isolation for recurring writers in Git repositories. +- Define what should be reported, ignored, retried, or escalated. +- Include a stop condition for monitors and follow-up loops. +- Never assume recurrence grants authority for new side effects. + +## Official Sources + +Product behavior in this guide was checked on 2026-08-20 against [Projects and chats](https://learn.chatgpt.com/docs/projects), [Long-running work](https://learn.chatgpt.com/docs/long-running-work), and [Scheduled tasks](https://learn.chatgpt.com/docs/automations). diff --git a/guides/skills-plugins-mcp-and-tools.md b/guides/skills-plugins-mcp-and-tools.md new file mode 100644 index 0000000..8890256 --- /dev/null +++ b/guides/skills-plugins-mcp-and-tools.md @@ -0,0 +1,68 @@ +# Skills, Plugins, MCP, And Tools + +These surfaces solve different reuse and integration problems. Use the smallest layer that changes behavior reliably. + +## The Layers + +### Instructions + +Use project instructions for stable rules that should apply whenever Codex works in a repository: conventions, privacy boundaries, important commands, and verification expectations. + +### Briefs And Checklists + +Use a Markdown resource when the workflow still needs human judgment and does not need automatic routing or code. + +### Scripts And Validators + +Use code for exact repeatable work such as parsing, schema checks, link validation, sorting, and release gates. + +### Skills + +A skill packages instructions and supporting resources for a repeatable task or workflow. It can include templates, examples, schemas, and helper scripts. + +Skills use progressive disclosure: compact metadata helps Codex decide when a skill applies, and the full instructions load only when selected. Clear descriptions and boundaries matter more than a large flat inventory. + +### Plugins + +A plugin is an installable bundle. It can contain skills, connectors backed by MCP, and optional custom UI. + +Use a plugin when a capability needs installation, distribution, connected tools, or a shared product surface. Installing a plugin does not mean every bundled capability should be enabled or trusted automatically. + +### MCP And Connectors + +MCP connects models to structured tools and context. Local Codex clients can connect directly to configured MCP servers; hosted surfaces commonly receive MCP-backed tools through plugins. + +Use tool allowlists and approval policies appropriate to the server. Prefer read-only tools for discovery and require review for writes or consequential actions. + +### Scheduled Tasks + +Use scheduled tasks when time or recurrence is part of the requirement. Put the reusable method in a skill when the scheduled prompt would otherwise duplicate a complex workflow. + +## Selection Rule + +| Need | Smallest useful layer | +| --- | --- | +| Stable repository rule | Project instruction | +| Human-guided reusable shape | Checklist or template | +| Exact deterministic operation | Script or validator | +| Reusable workflow expertise | Skill | +| Installable bundle or connected capability | Plugin | +| Structured external tools or context | MCP connector | +| Recurring execution | Scheduled task, often invoking a skill | + +## Capability State + +Do not confuse availability with use. A capability can be available, installed, enabled, visible or retrievable, activated, used, and finally verified. See [Capability Lifecycle And Prompt Visibility](capability-lifecycle.md). + +## Security Boundary + +- Inspect a plugin's manifest, skills, connectors, and hooks before enabling it. +- Treat third-party tool output as untrusted input. +- Do not put credentials in skills, prompts, examples, or repository configuration. +- Use the narrowest tool set and approval policy that supports the task. +- Read back external writes from the authoritative system. +- Do not publish an actual environment's inventory, endpoints, auth route, or security controls. + +## Official Sources + +Product behavior in this guide was checked on 2026-08-20 against [Skills and plugins](https://learn.chatgpt.com/docs/skills-and-plugins), [Build skills](https://learn.chatgpt.com/docs/build-skills), [Build plugins](https://learn.chatgpt.com/docs/build-plugins), [MCP](https://learn.chatgpt.com/docs/extend/mcp), and [Scheduled tasks](https://learn.chatgpt.com/docs/automations). diff --git a/guides/task-framing.md b/guides/task-framing.md index 4a330ea..f357d3b 100644 --- a/guides/task-framing.md +++ b/guides/task-framing.md @@ -2,7 +2,7 @@ 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 altitude. +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. @@ -18,9 +18,9 @@ Verification: Stop conditions: ``` -## The Higher-Altitude Frame +## The Higher-Abstraction Frame -For bigger work, I prefer this: +For bigger work, use a goal-shaped frame: ```markdown Goal: @@ -31,7 +31,7 @@ Context: First derive the task contract, source-of-truth map, delivery harness, and verification plan. Then execute. ``` -That tiny difference matters. You are not doing all the decomposition for Codex. You are giving it enough altitude and enough runway to design 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 decomposition. ## What To Include @@ -39,7 +39,7 @@ Name the real surface. If the task is about production, say production. If it is 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. -Name the proof. The strongest proof is deterministic: a test, diff, validator, API read-back, screenshot, or command output. When the work is subjective, state the taste or quality bar clearly enough that Codex can review against it. +Name the proof. Evidence must match the claim: tests and validators can check deterministic behavior, API read-backs can confirm service state, and browser inspection or screenshots can support rendered-state claims. None proves a different layer by itself. When the work is subjective, state the quality bar clearly enough for deliberate review. ## What To Avoid diff --git a/guides/team-adoption.md b/guides/team-adoption.md index 16b46de..653acc9 100644 --- a/guides/team-adoption.md +++ b/guides/team-adoption.md @@ -4,7 +4,7 @@ Codex adoption is not a tool rollout. It is work redesign. Teams get value when they turn recurring work into clearer inputs, better tool access, reviewable outputs, and feedback loops that actually show whether anything improved. -The altitude shift matters for teams too. The goal is not to train everyone to write tiny perfect prompts. The goal is to help people state outcomes, constraints, and success criteria so Codex can design a good path. +The abstraction level shift matters for teams too. The goal is not to train everyone to write tiny perfect prompts. The goal is to help people state outcomes, constraints, and success criteria so Codex can design a good path. ## Start With Workflows @@ -26,7 +26,7 @@ Then wrap the Codex loop around that workflow. Ask: - Can people frame the task as an outcome with proof? -- Can people choose the right thinking altitude? +- Can people choose the appropriate abstraction level? - Does Codex have access to the right source of truth? - Are writes gated at the right points? - Is there a deterministic check? diff --git a/guides/thinking-altitude.md b/guides/thinking-abstraction-level.md similarity index 68% rename from guides/thinking-altitude.md rename to guides/thinking-abstraction-level.md index 7b2bb37..f01cd54 100644 --- a/guides/thinking-altitude.md +++ b/guides/thinking-abstraction-level.md @@ -1,6 +1,6 @@ -# Thinking Altitude +# Thinking Abstraction Level -This is the biggest Codexmaxxing unlock for me. +Abstraction level is one of the most useful controls in agentic work. 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. @@ -15,31 +15,31 @@ flowchart TD E --> F["Codex executes and verifies"] ``` -The human job shifts from "write every step" to "choose the right altitude." +The human job shifts from "write every step" to "choose the right abstraction level." -## What Altitude Means +## What Abstraction Level Means -Thinking altitude is the level you hand the work over at. +Abstraction level describes how close a task statement is to the desired outcome versus an individual implementation action. -Low altitude: +Low abstraction level: ```markdown Change line 42 to use `color_temp_kelvin`. ``` -Medium altitude: +Medium abstraction level: ```markdown -Fix the light automation schema issue. Verify Home Assistant accepts the config and the old error stops appearing. +Fix the automation schema issue. Verify the target system accepts the configuration and the previous error stops appearing. ``` -Higher altitude: +Higher abstraction level: ```markdown -The home automations broke after an upgrade. Diagnose the likely failure layer, make the smallest safe fix, and verify the system is healthy again. +The automations broke after an upgrade. Diagnose the likely failure layer, make the smallest safe fix, and verify the affected workflow is healthy again. ``` -All three can be right. The maxxing move is knowing when Codex is capable of taking the higher-altitude version and designing the harness underneath it. +All three can be right. The useful judgment is knowing when Codex can take the higher-abstraction version and derive the work underneath it. ## The New Default @@ -61,7 +61,7 @@ Context: ``` -Then ask Codex to derive: +Then ask Codex to derive only the artifacts the work needs, such as: - the task contract, - the source-of-truth map, @@ -91,16 +91,18 @@ Stay lower when: - you already know the exact safe edit, - ambiguity would cause expensive churn. -## The Altitude Ladder +## The Abstraction Level Ladder -| Altitude | You Provide | Codex Provides | +| Abstraction Level | You Provide | Codex Provides | | --- | --- | --- | | 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 | Direction, boundaries, learning loop | Harness topology, decomposition, delegation, delivery path | -More altitude does not mean less clarity. It means clarity moves from steps to success criteria. +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. ## The Failure Mode @@ -110,9 +112,9 @@ The bad version of this is vague delegation: Make this better. ``` -That is not high altitude. That is fog. +That is not high abstraction. It is ambiguity. -High altitude still has a shape: +High-abstraction work still has a shape: ```markdown Make this repo feel like a public project someone would actually want to explore. @@ -121,7 +123,7 @@ Success criteria: - the README has a clear point of view, - the first-click paths are obvious, - internal maintenance notes are not part of the public surface, -- related repos are linked where useful, +- examples are synthetic and public-safe, - validation still passes. ``` diff --git a/guides/tools-skills-and-mcp.md b/guides/tools-skills-and-mcp.md deleted file mode 100644 index b4e44f0..0000000 --- a/guides/tools-skills-and-mcp.md +++ /dev/null @@ -1,62 +0,0 @@ -# Tools, Skills, And MCP - -Codex has a bunch of ways to get more capable. The trap is adding every shiny thing at once. - -Use the smallest thing that changes behavior reliably. - -At higher thinking altitude, tools and skills matter more. You are no longer asking Codex to do one edit. You are asking it to design and run a mini operating system around the goal. - -## The Ladder - -### Instructions - -Use project instructions for local rules that should always apply in a repo: test commands, privacy boundaries, coding conventions, browser routes, release gates. - -### Mission briefs - -Use a mission brief when you know the goal and success criteria but want Codex to derive the task contract, plan, and checks. - -### Templates and checklists - -Use Markdown resources when the workflow needs human judgment but not automation. A good template is often better than a premature tool. - -### Scripts and validators - -Use code when the check is deterministic: link validation, schema checks, formatting, package parity, release gates. - -### Skills - -Use a skill when a repeatable workflow needs instructions, examples, helper scripts, and routing rules. Skills are useful when "how to do the work" is itself reusable. - -### MCP tools - -Use MCP or connectors when Codex needs structured access to external systems: GitHub, docs, databases, issue trackers, browsers, internal knowledge, or APIs. - -### Automations - -Use automations for recurring checks, reminders, monitors, or scheduled reviews. Keep them read-only or draft-only unless the action boundary is very clear. - -## Selection Rule - -Ask: - -- Is this judgment? Use a guide or checklist. -- Is this exact and repeatable? Use a script or validator. -- Is this a recurring workflow? Use a skill. -- Does Codex need a real system? Use MCP or a connector. -- Does it need to happen on a schedule? Use an automation. -- Is the goal clear but the path unclear? Use a mission brief and let Codex derive the harness. - -## Tool Safety - -Tool access should come with boundaries: - -- default to read-only exploration, -- avoid printing secrets, -- use least privilege, -- require approval for external writes, -- verify with read-back after writes. - -## Verification - -The capability choice is right when it reduces repeated explanation, improves proof, and does not add more operational weight than the task deserves. diff --git a/resources/catalog.json b/resources/catalog.json index d9ff8b9..3ea2850 100644 --- a/resources/catalog.json +++ b/resources/catalog.json @@ -1,6 +1,6 @@ { - "version": "0.1.0", - "updated": "2026-06-04", + "version": "0.2.0", + "updated": "2026-08-20", "items": [ { "title": "The Codexmaxxing Loop", @@ -9,9 +9,9 @@ "status": "ready" }, { - "title": "Thinking Altitude", + "title": "Thinking Abstraction Level", "type": "guide", - "path": "guides/thinking-altitude.md", + "path": "guides/thinking-abstraction-level.md", "status": "ready" }, { @@ -39,9 +39,51 @@ "status": "ready" }, { - "title": "Tools, Skills, And MCP", + "title": "Skills, Plugins, MCP, And Tools", "type": "guide", - "path": "guides/tools-skills-and-mcp.md", + "path": "guides/skills-plugins-mcp-and-tools.md", + "status": "ready" + }, + { + "title": "Capability Lifecycle And Prompt Visibility", + "type": "guide", + "path": "guides/capability-lifecycle.md", + "status": "ready" + }, + { + "title": "Projects, Chats, Goals, And Scheduled Tasks", + "type": "guide", + "path": "guides/projects-chats-goals-and-schedules.md", + "status": "ready" + }, + { + "title": "Local, Worktree, And Cloud Environments", + "type": "guide", + "path": "guides/environments-worktrees-and-cloud.md", + "status": "ready" + }, + { + "title": "Browser, Computer Use, And Structured Connectors", + "type": "guide", + "path": "guides/browser-computer-use-and-connectors.md", + "status": "ready" + }, + { + "title": "Models, Reasoning, And Delegation", + "type": "guide", + "path": "guides/models-reasoning-and-delegation.md", + "status": "ready" + }, + { + "title": "Permissions, Rules, Hooks, And Instructions", + "type": "guide", + "path": "guides/permissions-rules-and-hooks.md", + "status": "ready" + }, + { + "title": "Artifacts, Sites, And Visualizations", + "type": "guide", + "path": "guides/artifacts-sites-and-visualizations.md", "status": "ready" }, { @@ -62,6 +104,36 @@ "path": "guides/team-adoption.md", "status": "ready" }, + { + "title": "Example Work Patterns", + "type": "examples", + "path": "docs/example-work-patterns.md", + "status": "usable" + }, + { + "title": "Field Synthesis", + "type": "research", + "path": "docs/field-synthesis.md", + "status": "reference" + }, + { + "title": "Product Claim Boundaries", + "type": "policy", + "path": "docs/product-claim-boundaries.md", + "status": "ready" + }, + { + "title": "Research Synthesis", + "type": "research", + "path": "docs/research-synthesis.md", + "status": "reference" + }, + { + "title": "Example Prompts And Workflows", + "type": "examples", + "path": "examples/README.md", + "status": "usable" + }, { "title": "Codex Operating Checklist", "type": "checklist", diff --git a/resources/codex-operating-checklist.md b/resources/codex-operating-checklist.md index ee3218a..0fc6df2 100644 --- a/resources/codex-operating-checklist.md +++ b/resources/codex-operating-checklist.md @@ -2,7 +2,7 @@ Use this before giving Codex a non-trivial mission. -## Altitude +## Abstraction Level - The ask is at the right level: exact edit, task, outcome, or broad goal. - Success criteria are clearer than the step list. @@ -26,12 +26,26 @@ Use this before giving Codex a non-trivial mission. ## Tools -- Required tools are available. +- Required 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 + +- 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 + +- 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. + ## Parallel Work - The harness topology is named: single-thread, hub-and-spoke, pipeline, specialist team, or portfolio. @@ -46,6 +60,13 @@ Use this before giving Codex a non-trivial mission. - Skipped checks will be reported. - The final answer will include what changed, what passed, and what remains. +## Output Surface + +- The result belongs in chat, 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. + ## Learning - Repeated lessons have a destination: instructions, template, script, skill, docs, or backlog. diff --git a/resources/playground-prompts.md b/resources/playground-prompts.md index db34692..8026be1 100644 --- a/resources/playground-prompts.md +++ b/resources/playground-prompts.md @@ -11,7 +11,7 @@ What I want: Ask me only the questions that would materially change the work. Otherwise make reasonable assumptions and give me: -- thinking altitude +- abstraction level - goal - success criteria - constraints @@ -36,7 +36,7 @@ Constraints: Context: -Before editing, choose the right thinking altitude and derive: +Before editing, choose the appropriate abstraction level and derive only what the work needs: - task contract - source-of-truth map - project harness @@ -83,7 +83,7 @@ Look for: - missing fixture/demo path - places where deterministic checks should replace manual judgment -Do not edit yet. First decide whether this should be handled as a narrow task or a higher-altitude repo improvement mission. Then return the smallest useful improvement plan. +Do not edit yet. First decide whether this should be handled as a narrow task or a higher-abstraction repository improvement mission. Then return the smallest useful improvement plan. ``` ## Debug A Real Thing Without Guessing diff --git a/resources/source-of-truth-map.md b/resources/source-of-truth-map.md index 5b03bde..093e6ec 100644 --- a/resources/source-of-truth-map.md +++ b/resources/source-of-truth-map.md @@ -4,7 +4,7 @@ Use this when a task spans repos, docs, live systems, or memory. ```markdown Task: -Thinking altitude: +Abstraction level: Current user instruction: diff --git a/resources/task-contract-template.md b/resources/task-contract-template.md index 7f2a09f..93ad633 100644 --- a/resources/task-contract-template.md +++ b/resources/task-contract-template.md @@ -26,6 +26,8 @@ Ask Codex to derive: ## Example +This example is synthetic and uses no real repository or environment details. + ```markdown Goal: Make this repo feel like a public project someone would actually want to explore. @@ -33,7 +35,7 @@ Make this repo feel like a public project someone would actually want to explore Success criteria: - the README has a clear point of view, - first-click paths are obvious, -- related repos are linked, +- examples are synthetic and public-safe, - examples show code and non-code use, - validation still passes. @@ -43,7 +45,7 @@ Constraints: - do not publish private examples. Context: -Start with README, guides, resources, examples, and related-project docs. +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. ``` diff --git a/resources/workflow-audit-template.md b/resources/workflow-audit-template.md index 1d01c48..3f2f048 100644 --- a/resources/workflow-audit-template.md +++ b/resources/workflow-audit-template.md @@ -8,7 +8,7 @@ Current owner: Current trigger: Current inputs: Current output: -Thinking altitude: +Abstraction level: Pain: Frequency: diff --git a/scripts/validate_content.py b/scripts/validate_content.py index 9108195..706301d 100755 --- a/scripts/validate_content.py +++ b/scripts/validate_content.py @@ -1,84 +1,247 @@ #!/usr/bin/env python3 -"""Validate Codexmaxxing content without external dependencies.""" +"""Validate public content and repository policy without external dependencies.""" from __future__ import annotations +import hashlib import json import re import sys +from datetime import date from pathlib import Path +from urllib.parse import urlsplit ROOT = Path(__file__).resolve().parents[1] -CATALOG = ROOT / "resources" / "catalog.json" -CATALOGED_DIRS = {"guides", "resources"} -PRIVATE_PATTERNS = [ - re.compile(r"/Users/[A-Za-z0-9._-]+"), - re.compile(r"(?\"']+") +ISO_DATE_PATTERN = re.compile(r"\b\d{4}-\d{2}-\d{2}\b") +FIRST_PERSON_PATTERN = re.compile( + r"(? None: print(f"ERROR: {message}") -def markdown_files() -> list[Path]: - ignored = {".git"} - files: list[Path] = [] - for path in ROOT.rglob("*.md"): - if any(part in ignored for part in path.parts): - continue - files.append(path) - return sorted(files) +def relative(path: Path, root: Path) -> str: + return path.relative_to(root).as_posix() + +def is_ignored(path: Path) -> bool: + return any(part in IGNORED_DIRS for part in path.parts) + + +def markdown_files(root: Path) -> list[Path]: + return sorted( + path + for path in root.rglob("*.md") + if not is_ignored(path) and not path.is_symlink() + ) + + +def public_text_files(root: Path) -> list[Path]: + return sorted( + path + for path in root.rglob("*") + if path.is_file() + and not path.is_symlink() + and path.suffix.lower() in PUBLIC_TEXT_SUFFIXES + and not is_ignored(path) + ) -def validate_catalog(errors: list[str]) -> None: - if not CATALOG.exists(): - errors.append("resources/catalog.json is missing") + +def catalogable_paths(root: Path) -> set[str]: + paths: set[str] = set() + for dirname in CATALOGED_DIRS: + for path in sorted((root / dirname).glob("*.md")): + if path.name != "README.md": + paths.add(relative(path, root)) + for rel_path in CATALOGED_EXTRA_FILES: + if (root / rel_path).exists(): + paths.add(rel_path.as_posix()) + return paths + + +def valid_iso_date(value: object) -> bool: + if not isinstance(value, str): + return False + try: + return date.fromisoformat(value).isoformat() == value + except ValueError: + return False + + +def validate_catalog(root: Path, errors: list[str]) -> None: + catalog_file = root / CATALOG_PATH + if not catalog_file.exists() or catalog_file.is_symlink(): + errors.append(f"{CATALOG_PATH.as_posix()} is missing") return try: - catalog = json.loads(CATALOG.read_text(encoding="utf-8")) - except json.JSONDecodeError as exc: - errors.append(f"resources/catalog.json is invalid JSON: {exc}") + catalog = json.loads(catalog_file.read_text(encoding="utf-8")) + except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc: + errors.append(f"{CATALOG_PATH.as_posix()} is invalid JSON: {exc}") + return + + if not isinstance(catalog, dict): + errors.append(f"{CATALOG_PATH.as_posix()} must contain a JSON object") return + if not valid_iso_date(catalog.get("updated")): + errors.append(f"{CATALOG_PATH.as_posix()} must contain a valid updated date") items = catalog.get("items") if not isinstance(items, list) or not items: - errors.append("resources/catalog.json must contain a non-empty items list") + errors.append(f"{CATALOG_PATH.as_posix()} must contain a non-empty items list") return catalog_paths: set[str] = set() + titles: set[str] = set() for index, item in enumerate(items): if not isinstance(item, dict): errors.append(f"catalog item {index} must be an object") continue + + title = item.get("title") rel_path = item.get("path") - if not rel_path: + item_type = item.get("type") + status = item.get("status") + if not isinstance(title, str) or not title.strip(): + errors.append(f"catalog item {index} is missing title") + elif title in titles: + errors.append(f"catalog title is duplicated: {title}") + else: + titles.add(title) + + if not isinstance(rel_path, str) or not rel_path: errors.append(f"catalog item {index} is missing path") continue + rel = Path(rel_path) + if rel.is_absolute() or ".." in rel.parts: + errors.append(f"catalog item {index} has an unsafe path") + continue + if rel_path in catalog_paths: + errors.append(f"catalog path is duplicated: {rel_path}") catalog_paths.add(rel_path) - target = ROOT / rel_path - if not target.exists(): + target = root / rel + if not target.is_file() or target.is_symlink(): errors.append(f"catalog path does not exist: {rel_path}") - for dirname in CATALOGED_DIRS: - for path in sorted((ROOT / dirname).glob("*.md")): - if path.name == "README.md": - continue - rel = str(path.relative_to(ROOT)) - if rel not in catalog_paths: - errors.append(f"{rel} is missing from resources/catalog.json") + if item_type not in KNOWN_CATALOG_TYPES: + errors.append(f"catalog item {index} has unknown type: {item_type}") + if status not in KNOWN_CATALOG_STATUSES: + errors.append(f"catalog item {index} has unknown status: {status}") + + for rel_path in sorted(catalogable_paths(root) - catalog_paths): + errors.append(f"{rel_path} is missing from {CATALOG_PATH.as_posix()}") -def validate_guide_headings(errors: list[str]) -> None: - for path in sorted((ROOT / "guides").glob("*.md")): +def validate_guide_headings(root: Path, errors: list[str]) -> None: + for path in sorted((root / "guides").glob("*.md")): if path.name == "README.md": continue - first_line = path.read_text(encoding="utf-8").splitlines()[0] - if not first_line.startswith("# "): - errors.append(f"{path.relative_to(ROOT)} must start with an H1") + lines = path.read_text(encoding="utf-8").splitlines() + if not lines or not lines[0].startswith("# "): + errors.append(f"{relative(path, root)} must start with an H1") def is_external_link(target: str) -> bool: @@ -90,8 +253,8 @@ def is_external_link(target: str) -> bool: ) -def validate_markdown_links(errors: list[str]) -> None: - for path in markdown_files(): +def validate_markdown_links(root: Path, errors: list[str]) -> None: + for path in markdown_files(root): text = path.read_text(encoding="utf-8") for match in LINK_PATTERN.finditer(text): target = match.group(1).strip() @@ -102,43 +265,416 @@ def validate_markdown_links(errors: list[str]) -> None: continue resolved = (path.parent / target_path).resolve() try: - resolved.relative_to(ROOT) + resolved.relative_to(root.resolve()) except ValueError: - errors.append(f"{path.relative_to(ROOT)} links outside repo: {target}") + errors.append(f"{relative(path, root)} links outside the repository") continue if not resolved.exists(): - errors.append(f"{path.relative_to(ROOT)} has broken link: {target}") + errors.append(f"{relative(path, root)} has a broken local link") + + +def private_pattern_names(text: str) -> list[str]: + return [name for name, pattern in PRIVATE_PATTERNS if pattern.search(text)] + + +def validate_public_safety(root: Path, errors: list[str]) -> None: + for path in public_text_files(root): + text = path.read_text(encoding="utf-8") + for name in private_pattern_names(text): + errors.append(f"{relative(path, root)} contains a prohibited {name}") + if re.search(r"\baltitude\b", text, re.IGNORECASE): + errors.append( + f"{relative(path, root)} uses the retired term 'altitude'; " + "use 'abstraction level'" + ) + + for path in root.rglob("*"): + if is_ignored(path): + continue + if re.search(r"\baltitude\b", path.name, re.IGNORECASE): + errors.append( + f"{relative(path, root)} uses the retired term in a file or directory name" + ) + + +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(".,;:!?)]}") -def validate_private_patterns(errors: list[str]) -> None: - for path in markdown_files() + [CATALOG]: - if not path.exists(): +def external_url_issue(raw_url: str) -> str | None: + url = normalize_url(raw_url) + if url in NON_FETCHING_URL_EXCEPTIONS: + return None + parsed = urlsplit(url) + if parsed.scheme != "https": + return "must use HTTPS" + if parsed.username or parsed.password: + return "must not contain embedded credentials" + hostname = (parsed.hostname or "").lower() + if hostname not in ALLOWED_EXTERNAL_HOSTS: + return "uses a host outside the reviewed allowlist" + return None + + +def validate_external_urls(root: Path, errors: list[str]) -> None: + for path in public_text_files(root): + text = path.read_text(encoding="utf-8") + for match in URL_PATTERN.finditer(text): + issue = external_url_issue(match.group(0)) + if issue: + errors.append(f"{relative(path, root)} contains an external URL that {issue}") + + +def validate_current_product_sources(root: Path, errors: list[str]) -> None: + for rel_path in sorted(CURRENT_PRODUCT_DOCUMENTS): + path = root / rel_path + if not path.is_file(): + errors.append(f"current-product document is missing: {rel_path.as_posix()}") continue text = path.read_text(encoding="utf-8") - for pattern in PRIVATE_PATTERNS: - if pattern.search(text): - errors.append(f"{path.relative_to(ROOT)} contains private-looking value: {pattern.pattern}") + if "## Official Sources" not in text: + errors.append(f"{rel_path.as_posix()} is missing an Official Sources section") + dates = ISO_DATE_PATTERN.findall(text) + if not dates or not any(valid_iso_date(value) for value in dates): + errors.append(f"{rel_path.as_posix()} is missing a valid verification date") + if "https://learn.chatgpt.com/" not in text: + errors.append(f"{rel_path.as_posix()} is missing a current official source") + +def png_forbidden_chunks(data: bytes) -> set[str]: + if not data.startswith(b"\x89PNG\r\n\x1a\n"): + raise ValueError("invalid PNG signature") + forbidden = {b"eXIf", b"iTXt", b"tEXt", b"zTXt"} + found: set[str] = set() + offset = 8 + saw_iend = False + while offset < len(data): + if offset + 12 > len(data): + raise ValueError("truncated PNG chunk") + length = int.from_bytes(data[offset : offset + 4], "big") + chunk_type = data[offset + 4 : offset + 8] + end = offset + 12 + length + if end > len(data): + raise ValueError("invalid PNG chunk length") + if chunk_type in forbidden: + found.add(chunk_type.decode("ascii")) + offset = end + if chunk_type == b"IEND": + saw_iend = True + break + if not saw_iend: + raise ValueError("missing PNG IEND chunk") + if offset != len(data): + raise ValueError("trailing data after PNG IEND chunk") + return found -def validate_code_fences(errors: list[str]) -> None: - fence_pattern = re.compile(r"^`{3,}") - for path in markdown_files(): - fence_count = 0 + +def webp_forbidden_chunks(data: bytes) -> set[str]: + if len(data) < 12 or data[:4] != b"RIFF" or data[8:12] != b"WEBP": + raise ValueError("invalid WebP header") + declared_size = int.from_bytes(data[4:8], "little") + 8 + if declared_size != len(data): + raise ValueError("WebP size does not match its RIFF header") + forbidden = {b"EXIF", b"XMP "} + found: set[str] = set() + offset = 12 + while offset + 8 <= declared_size: + chunk_type = data[offset : offset + 4] + length = int.from_bytes(data[offset + 4 : offset + 8], "little") + end = offset + 8 + length + if end > declared_size: + raise ValueError("invalid WebP chunk length") + if chunk_type in forbidden: + found.add(chunk_type.decode("ascii")) + offset = end + (length % 2) + return found + + +def svg_security_issues(text: str) -> list[str]: + checks = { + "document type or entity declaration": r" None: + rel_path = relative(path, root) + try: + data = path.read_bytes() + if path.suffix.lower() == ".png": + found = png_forbidden_chunks(data) + if found: + errors.append(f"{rel_path} contains prohibited PNG metadata chunks") + elif path.suffix.lower() == ".webp": + found = webp_forbidden_chunks(data) + if found: + errors.append(f"{rel_path} contains prohibited WebP metadata chunks") + elif path.suffix.lower() == ".svg": + issues = svg_security_issues(data.decode("utf-8")) + for issue in issues: + errors.append(f"{rel_path} contains prohibited SVG {issue}") + else: + errors.append(f"{rel_path} uses an unreviewed asset format") + except (OSError, UnicodeDecodeError, ValueError) as exc: + errors.append(f"{rel_path} failed asset inspection: {exc}") + + +def validate_asset_manifest(root: Path, errors: list[str]) -> None: + manifest_file = root / ASSET_MANIFEST_PATH + if not manifest_file.exists() or manifest_file.is_symlink(): + errors.append(f"{ASSET_MANIFEST_PATH.as_posix()} is missing") + return + try: + manifest = json.loads(manifest_file.read_text(encoding="utf-8")) + except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc: + errors.append(f"{ASSET_MANIFEST_PATH.as_posix()} is invalid JSON: {exc}") + return + if not isinstance(manifest, dict): + errors.append(f"{ASSET_MANIFEST_PATH.as_posix()} must contain a JSON object") + return + if not valid_iso_date(manifest.get("reviewed_on")): + errors.append(f"{ASSET_MANIFEST_PATH.as_posix()} needs a valid reviewed_on date") + + items = manifest.get("assets") + if not isinstance(items, list) or not items: + errors.append(f"{ASSET_MANIFEST_PATH.as_posix()} must contain reviewed assets") + return + + manifest_paths: set[str] = set() + for index, item in enumerate(items): + if not isinstance(item, dict): + errors.append(f"asset manifest item {index} must be an object") + continue + rel_path = item.get("path") + digest = item.get("sha256") + checks = item.get("checks") + if not isinstance(rel_path, str) or not rel_path.startswith("assets/"): + errors.append(f"asset manifest item {index} has an invalid path") + continue + rel = Path(rel_path) + if rel.is_absolute() or ".." in rel.parts: + errors.append(f"asset manifest item {index} has an unsafe path") + continue + if rel_path in manifest_paths: + errors.append(f"asset manifest path is duplicated: {rel_path}") + manifest_paths.add(rel_path) + asset = root / rel + if not asset.is_file() or asset.is_symlink(): + errors.append(f"asset manifest path does not exist: {rel_path}") + continue + if not isinstance(digest, str) or not SHA256_PATTERN.fullmatch(digest): + errors.append(f"asset manifest item {index} has an invalid SHA-256") + else: + actual_digest = hashlib.sha256(asset.read_bytes()).hexdigest() + if digest != actual_digest: + errors.append(f"{rel_path} changed after its recorded review") + if not isinstance(checks, list) or set(checks) != {"metadata", "privacy", "visual"}: + errors.append( + f"asset manifest item {index} must record metadata, privacy, and visual checks" + ) + validate_asset_metadata(asset, errors, root) + + assets_dir = root / "assets" + if not assets_dir.is_dir(): + errors.append("assets directory is missing") + return + actual_paths = { + relative(path, root) + for path in assets_dir.rglob("*") + if path.is_file() and path != manifest_file + } + for rel_path in sorted(actual_paths - manifest_paths): + errors.append(f"{rel_path} is missing from {ASSET_MANIFEST_PATH.as_posix()}") + for rel_path in sorted(manifest_paths - actual_paths): + errors.append(f"{rel_path} is stale in {ASSET_MANIFEST_PATH.as_posix()}") + + +def is_pinned_action_reference(reference: str) -> bool: + if reference.startswith("./"): + return True + if "@" not in reference: + return False + return bool(FULL_SHA_PATTERN.fullmatch(reference.rsplit("@", 1)[1])) + + +def top_level_block(text: str, key: str) -> list[str] | None: + lines = text.splitlines() + target = f"{key}:" + for index, line in enumerate(lines): + if line != target: + continue + block: list[str] = [] + for candidate in lines[index + 1 :]: + if not candidate.strip(): + continue + if not candidate.startswith((" ", "\t")): + break + block.append(candidate.strip()) + return block + return None + + +def workflow_job_blocks(text: str) -> dict[str, str]: + lines = text.splitlines() + try: + jobs_index = lines.index("jobs:") + except ValueError: + return {} + job_starts: list[tuple[int, str]] = [] + for index in range(jobs_index + 1, len(lines)): + line = lines[index] + if line and not line.startswith((" ", "\t")): + break + match = re.fullmatch(r" ([A-Za-z0-9_-]+):\s*", line) + if match: + job_starts.append((index, match.group(1))) + blocks: dict[str, str] = {} + for offset, (start, name) in enumerate(job_starts): + end = job_starts[offset + 1][0] if offset + 1 < len(job_starts) else len(lines) + blocks[name] = "\n".join(lines[start:end]) + return blocks + + +def validate_workflow_policy(root: Path, errors: list[str]) -> None: + path = root / WORKFLOW_PATH + if not path.is_file() or path.is_symlink(): + errors.append(f"{WORKFLOW_PATH.as_posix()} is missing") + return + text = path.read_text(encoding="utf-8") + if top_level_block(text, "permissions") != ["contents: read"]: + errors.append( + f"{WORKFLOW_PATH.as_posix()} must grant only top-level contents: read" + ) + + job_blocks = workflow_job_blocks(text) + if not job_blocks: + errors.append(f"{WORKFLOW_PATH.as_posix()} must declare at least one job") + for job_name, block in job_blocks.items(): + if not re.search(r"(?m)^ runs-on:\s*ubuntu-24\.04\s*$", block): + errors.append( + f"{WORKFLOW_PATH.as_posix()} job {job_name} must use the reviewed runner image" + ) + timeout_match = re.search(r"(?m)^ timeout-minutes:\s*(\d+)\s*$", block) + if not timeout_match: + errors.append( + f"{WORKFLOW_PATH.as_posix()} job {job_name} must set a timeout" + ) + elif int(timeout_match.group(1)) > 15: + errors.append( + f"{WORKFLOW_PATH.as_posix()} job {job_name} timeout must be 15 minutes or less" + ) + if "pull_request_target" in text: + errors.append(f"{WORKFLOW_PATH.as_posix()} must not use pull_request_target") + if re.search(r"\bsecrets?\b", text, re.IGNORECASE): + errors.append(f"{WORKFLOW_PATH.as_posix()} must not consume repository secrets") + + references = re.findall(r"(?m)^[ \t]*-[ \t]+uses:[ \t]*([^\s#]+)", text) + if not references: + errors.append(f"{WORKFLOW_PATH.as_posix()} must declare its actions explicitly") + for reference in references: + if not is_pinned_action_reference(reference): + errors.append( + f"{WORKFLOW_PATH.as_posix()} uses an action without an immutable SHA pin" + ) + + checkout_match = re.search( + r"(?m)^[ \t]*-[ \t]+uses:[ \t]*actions/checkout@[0-9a-f]{40}[^\n]*$", + text, + ) + if not checkout_match: + errors.append(f"{WORKFLOW_PATH.as_posix()} must use a pinned checkout action") + else: + next_step = re.search(r"(?m)^ {6}-[ \t]+", text[checkout_match.end() :]) + block_end = ( + checkout_match.end() + next_step.start() if next_step else len(text) + ) + checkout_block = text[checkout_match.start() : block_end] + if "persist-credentials: false" not in checkout_block: + errors.append( + f"{WORKFLOW_PATH.as_posix()} must disable persisted checkout credentials" + ) + + +def validate_code_fences(root: Path, errors: list[str]) -> None: + for path in markdown_files(root): + active_fence: str | None = None for line in path.read_text(encoding="utf-8").splitlines(): - if fence_pattern.match(line): - fence_count += 1 - if fence_count % 2: - errors.append(f"{path.relative_to(ROOT)} has an unbalanced code fence") + match = FENCE_PATTERN.match(line) + if not match: + continue + marker = match.group(1)[0] + if active_fence is None: + active_fence = marker + elif active_fence == marker: + active_fence = None + if active_fence is not None: + errors.append(f"{relative(path, root)} has an unbalanced code fence") -def main() -> int: +def validate_no_symlinks(root: Path, errors: list[str]) -> None: + for path in root.rglob("*"): + if not is_ignored(path) and path.is_symlink(): + errors.append(f"{relative(path, root)} is a prohibited symbolic link") + + +def validate_repository(root: Path = ROOT) -> list[str]: errors: list[str] = [] - validate_catalog(errors) - validate_guide_headings(errors) - validate_markdown_links(errors) - validate_private_patterns(errors) - validate_code_fences(errors) + validate_no_symlinks(root, errors) + validate_catalog(root, errors) + 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) + validate_workflow_policy(root, errors) + validate_code_fences(root, errors) + return errors + +def main() -> int: + errors = validate_repository() if errors: for error in errors: fail(error) diff --git a/tests/test_validate_content.py b/tests/test_validate_content.py new file mode 100644 index 0000000..4c1dd9b --- /dev/null +++ b/tests/test_validate_content.py @@ -0,0 +1,69 @@ +"""Focused regression tests for the public-content validator.""" + +from __future__ import annotations + +import importlib.util +import unittest +from pathlib import Path + +VALIDATOR_PATH = Path(__file__).resolve().parents[1] / "scripts" / "validate_content.py" +SPEC = importlib.util.spec_from_file_location("validate_content", VALIDATOR_PATH) +if SPEC is None or SPEC.loader is None: + raise RuntimeError("Unable to load validator") +validator = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(validator) + + +class ValidatorSafeguardTests(unittest.TestCase): + def test_private_pattern_categories_do_not_return_matched_values(self) -> None: + text = "Contact " + "reader" + "@example.com from 192.168.1.20." + self.assertEqual( + validator.private_pattern_names(text), + ["email address", "private IPv4 address"], + ) + + def test_external_url_policy_is_allowlist_based(self) -> None: + self.assertIsNone( + validator.external_url_issue("https://learn.chatgpt.com/docs/models") + ) + self.assertEqual( + validator.external_url_issue("https://example.com/profile"), + "uses a host outside the reviewed allowlist", + ) + + def test_action_references_require_full_commit_sha(self) -> None: + self.assertTrue( + validator.is_pinned_action_reference( + "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1" + ) + ) + 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_svg_active_content_is_detected(self) -> None: + self.assertEqual( + validator.svg_security_issues(''), + ["script content", "event-handler attribute"], + ) + + def test_png_metadata_and_trailing_payloads_are_detected(self) -> None: + def chunk(kind: bytes, payload: bytes = b"") -> bytes: + return len(payload).to_bytes(4, "big") + kind + payload + b"\x00\x00\x00\x00" + + signature = b"\x89PNG\r\n\x1a\n" + image_end = chunk(b"IEND") + self.assertEqual( + validator.png_forbidden_chunks( + signature + chunk(b"tEXt", b"synthetic") + image_end + ), + {"tEXt"}, + ) + with self.assertRaisesRegex(ValueError, "trailing data"): + validator.png_forbidden_chunks(signature + image_end + b"payload") + + +if __name__ == "__main__": + unittest.main()