final optimization layer

Author: DavidQ

.codex/README_AUTOMATION.md

@@ -0,0 +1,12 @@
+# Codex Automation Layout
+
+Codex already auto-loads AGENTS.md from the repo root.
+
+Use this folder for project-local Codex helpers:
+- skills/ for reusable workflows that should load only when invoked
+- optional project config later if needed
+
+Recommended usage:
+1. Keep AGENTS.md at repo root
+2. Keep start_of_day lightweight
+3. Use the repo-build skill when you want Codex to execute a BUILD with packaging

.codex/skills/repo-build/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: repo-build
+description: Use when executing a single BUILD_PR in this repository that must stay surgically scoped, validate exactly what the BUILD asks, and package a repo-structured delta ZIP under <project folder>/tmp/.
+---
+
+Follow this workflow:
+
+1. Read the active BUILD_PR document first.
+2. Confirm the PR purpose is singular.
+3. Read only exact target files and immediate dependencies.
+4. Implement only the approved BUILD scope.
+5. Run only the requested validation.
+6. Report exact files changed, exact validation performed, and exact ZIP path.
+7. Package a repo-structured delta ZIP under <project folder>/tmp/.
+8. Stop after BUILD output is complete.
+
+Fail fast if:
+- the BUILD doc is vague
+- target files are missing or contradictory
+- the request expands beyond one PR purpose
+- the exact ZIP path is missing
+- the result would not be testable

AGENTS.md

@@ -2,30 +2,31 @@
 
 ## Workflow
 - PLAN -> BUILD -> APPLY
-- Docs-first unless the active task is BUILD or APPLY
-- One PR per purpose
-- Smallest scoped valid change only
+- BUILD is the normal Codex phase
+- One PR purpose only
+- Smallest scoped valid implementation only
 
 ## Repo Rules
-- Codex writes code
-- No engine core changes unless the task explicitly requires it
-- Sample-level integration only unless the task explicitly requires broader scope
-- Read target files first
-- Avoid repo-wide scanning unless exact targets require it
-- No speculative exploration
+- Follow the BUILD doc as source of truth
+- Read exact target files first
+- Avoid repo-wide scans unless exact targets require them
 - Stop and report on ambiguity
+- Do not modify engine core unless explicitly in scope
+- Do not modify start_of_day folders unless explicitly requested
 
-## Packaging
-- Package results to <project folder>/tmp/*.zip
-- Preserve exact repo-relative structure inside the ZIP
-- Include only files relevant to the PR
-- Do not include unrelated files, full-repo copies, dependencies, or build artifacts
+## Windows Execution
+- Prefer Node.js or Python for file operations, rename work, path handling, and ZIP work
+- Avoid PowerShell for path-heavy work unless explicitly required
+- If PowerShell is required, use Join-Path or [System.IO.Path]::Combine(...)
 
-## BUILD Expectations
-- Exact file targets only
-- Explicit validation commands
-- No unrelated changes
-- No retry without a corrected spec
+## Packaging
+- Every BUILD must produce a repo-structured delta ZIP
+- ZIP output path: <project folder>/tmp/<TASK_NAME>_delta.zip
+- Do not stage ZIP files from <project folder>/tmp/
 
-## Architecture
-TOOLS -> CONTRACT -> RUNTIME -> DEBUG -> VISUAL
+## BUILD Quality
+- Exact targets required
+- Exact validation required
+- No vague wording
+- No unrelated cleanup
+- Prefer testable vertical slices

docs/dev/FINAL_OPTIMIZATION_INSTRUCTIONS.md

@@ -0,0 +1,21 @@
+# Final Optimization Layer
+
+## What changed
+
+You now use:
+- ultra-compact BUILD_PR docs
+- one-line Codex command
+
+## BUILD_PR rules
+- max ~10 lines
+- no repetition
+- only exact files + changes + validation
+
+## Codex command
+- 1–3 lines only
+- no repeated rules (AGENTS.md handles them)
+
+## Result
+- minimum tokens
+- fastest Codex runs
+- lowest failure rate

docs/dev/FULL_AUTOMATION_NOTES.md

@@ -0,0 +1,14 @@
+# Full Automation Notes
+
+This setup automates the repeated instruction load by splitting responsibility:
+
+- AGENTS.md = auto-loaded durable repo guidance
+- .codex/skills/repo-build/SKILL.md = reusable BUILD execution workflow loaded when invoked
+- start_of_day/codex/CODEX_CORE.md = tiny daily reminder only
+- CODEX_AUTO_COMMAND.md = minimal trigger command
+
+Daily flow:
+1. Load CODEX_CORE.md and EXECUTION_GATE.md
+2. Run the minimal command from docs/dev/templates/CODEX_AUTO_COMMAND.md
+3. Point Codex at PLAN_PR + BUILD_PR
+4. Codex uses AGENTS.md and repo-build skill to stay on rails

docs/dev/PROJECT_INSTRUCTIONS.md

@@ -0,0 +1,28 @@
+# PROJECT INSTRUCTIONS
+
+You are working in a docs-first repo workflow.
+
+Workflow:
+PLAN_PR → BUILD_PR → APPLY_PR
+
+Rules:
+- One PR purpose only
+- Smallest scoped valid change
+- BUILD must be one-pass executable
+- No vague wording
+- No repo-wide scanning unless required
+
+Responsibilities:
+- ChatGPT: create plans, PR docs, and ZIP bundles
+- Codex: writes implementation code
+- User: runs Codex + validates
+
+Output rules:
+- Always produce repo-structured ZIPs
+- Place ZIPs under <project folder>/tmp/
+- Preserve exact repo structure inside ZIP
+
+Do not:
+- Write implementation code unless explicitly asked
+- Expand scope beyond the PR
+- Modify start_of_day folders unless requested

docs/dev/start_of_day/chatGPT/_remember NEW SESSION.txt

@@ -0,0 +1 @@
+./docs/dev/PROJECT_INSTRUCTIONS

docs/dev/start_of_day/codex/BUILD_EXECUTION_CHECKLIST.md

@@ -0,0 +1,21 @@
+# Codex SOD Cleanup Instructions
+
+## KEEP (load daily)
+- CODEX_CORE.md
+- EXECUTION_GATE.md
+- USAGE_REMINDER.md (optional)
+
+## DELETE or stop loading daily
+- RULES.md
+- WORKFLOW.md
+- BUILD_EXECUTION_CHECKLIST.md
+- STOP_AND_REPORT.md
+- README.md (codex SOD version)
+- CHANGES_SUMMARY.txt
+
+## KEEP in repo, but do not paste daily
+- AGENTS.md
+- .codex/skills/repo-build/SKILL.md
+
+## Result
+Daily Codex startup becomes 2-3 small files instead of a larger repeated bundle.