Configure default codex rules

.codex/rules/default.rules

@@ -0,0 +1,4 @@
+prefix_rule(pattern=["uv"], decision="allow")
+prefix_rule(pattern=["gh"], decision="allow")
+prefix_rule(pattern=["just"], decision="allow")
+prefix_rule(pattern=["git"], decision="allow")

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

@@ -0,0 +1,42 @@
+---
+name: agentify-repo
+description: "Incrementally add harness and tooling to an existing repo so it converges toward zach-stack safely over multiple passes."
+---
+
+# Agentify Repo
+
+Use this skill when asked to make an existing repo more agent-friendly without one-shot rewrites.
+
+## Core goal
+
+If required dependencies are not installed in the current environment, bootstrap them first:
+
+- `$install-skills https://github.com/openai/skills/tree/main/skills/.custom/zach-stack`
+- `$install-skills https://github.com/openai/skills/tree/main/skills/.custom/configure-codex`
+
+Set up harness/tooling in small, reversible steps that make the repo more verifiable and easier for agents to work with.
+
+## Recommended flow
+
+1. Baseline assessment: detect current stack, docs state, tests, lints, and CI.
+2. Harness setup phase: add/update only low-risk structure first (`docs/`, `Justfile`, command discoverability, test map).
+3. Apply `zach-stack`-aligned improvements in small batches:
+   - tooling defaults relevant to current stack
+   - testing additions by priority
+   - docs upkeep and file ownership mapping
+4. Validate each phase.
+5. Pause with explicit next milestone.
+
+## Hard rules
+
+- No broad migration in one run unless explicitly authorized.
+- Prefer additive changes and stable commit points.
+- If unknown/legacy constraints exist, defer and document them instead of forcing defaults.
+- Ask before any environment or rules-file changes that require trust-sensitive decisions.
+
+## References
+
+- `references/incremental-harness.md`
+- `references/convergence-phases.md`
+- `references/rollback-and-safety.md`
+- `../zach-stack` for target conventions.

.codex/skills/agentify-repo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Agentify Repo"
+  short_description: "Incrementally harden existing repos with zach-stack conventions."
+  default_prompt: "Use $agentify-repo to add agent-friendly tooling in safe milestones."

.codex/skills/agentify-repo/references/convergence-phases.md

@@ -0,0 +1,19 @@
+# Convergence phases
+
+## Phase 0: Discovery
+
+- Detect existing stack and constraints.
+- Record what cannot be changed safely in one pass.
+
+## Phase 1: Surface hardening
+
+- Docs + Justfile + lightweight test discoverability.
+- Add project-specific lint/test quick checks.
+
+## Phase 2: Toolchain alignment
+
+- Add `zach-stack` defaults where they do not disrupt current architecture.
+
+## Phase 3+: Optional deepening
+
+- Introduce additional stack pieces (workspaces, visualization layout, docs automation, etc.) as explicit follow-up passes.

.codex/skills/agentify-repo/references/incremental-harness.md

@@ -0,0 +1,16 @@
+# Incremental harness setup
+
+## Purpose
+
+Build the operating surface needed for agents before enforcing deeper stack shifts.
+
+## Initial changes (safe first)
+
+- Add/normalize `docs/` with a current file-map and runbook.
+- Add/refresh `Justfile` command palette.
+- Introduce a lightweight test index and smoke test list.
+- Clarify command/tool ownership in docs.
+
+## Principle
+
+The harness layer should reduce uncertainty first: if agents can discover and run stable commands, deeper changes are cheaper and safer.

.codex/skills/agentify-repo/references/rollback-and-safety.md

@@ -0,0 +1,20 @@
+# Rollback and safety
+
+## Why it matters
+
+Incremental changes are useful only if each step is reversible.
+
+## Safety pattern
+
+- Make one conceptual category of change at a time.
+- Validate commands and tests after each change set.
+- Record a simple checkpoint note:
+  - What changed
+  - Why it changed
+  - How to revert
+
+## Example rollback triggers
+
+- Unexpected behavioral diff
+- Test coverage mismatch introduced by command changes
+- Documentation or automation drift

.codex/skills/configure-codex/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: configure-codex
+description: "Conservatively configure `.codex/rules/default.rules` and Codex environment setup for repo and user ergonomics."
+---
+
+# Configure Codex
+
+Use this skill when asked to update Codex rules, command permissions, or environment setup for repository work.
+
+## Scope
+- `.codex/rules/default.rules` updates.
+- Command allow-list selection.
+- Codex environment/worktree ergonomics.
+- Guidance for repo-scoped vs user-scoped settings.
+
+## Guarded workflow
+
+1. Inventory current constraints and user intent.
+2. Propose only relevant allowed command families (e.g., uv, just, pnpm, gh, glab).
+3. Ask for confirmation before writing rule updates.
+4. Apply minimally and explain impact.
+5. Validate the new command surface and leave a follow-up note.
+
+## Conservative defaults
+
+- Keep allow-lists minimal.
+- Prefer repo-only permissions over broad global overrides.
+- Add no commands that are not used by the project.
+
+## Troubleshooting
+
+- If `.codex/rules` is not writable in the current workspace, update the user-level `/Users/zach.parent/.codex/rules/default.rules` after confirming scope and keep that in notes.
+
+## References
+
+- `references/rules-default.md`
+- `references/allowed-commands-matrix.md`
+- `references/codex-environment.md`

.codex/skills/configure-codex/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Configure Codex"
+  short_description: "Set up codex rules and environment configuration safely."
+  default_prompt: "Use $configure-codex to propose and apply safe Codex configuration updates."

.codex/skills/configure-codex/references/allowed-commands-matrix.md

@@ -0,0 +1,17 @@
+# Allowed command matrix (`configure-codex`)
+
+## Always avoid by default
+
+- Blanket escalation of broad shell commands.
+- Universal global allow-lists without project need.
+
+## Recommended matrix by project type
+
+- **Web-first**: `pnpm`, `just`, `gh`, optional `uv`.
+- **Python-first**: `uv`, `just`, `gh`, optional `glab`.
+- **Mixed**: web + python commands only where actively used.
+
+## Confirmation requirements
+
+- Ask before enabling commands not currently used by the repo.
+- Keep user-visible logs of every newly enabled command.

.codex/skills/configure-codex/references/codex-environment.md

@@ -0,0 +1,19 @@
+# Codex environment and worktree setup
+
+## Objective
+
+Make agent work predictable and repeatable in local and customer environments.
+
+## Setup areas
+
+- command presets for project startup
+- worktree naming and path strategy
+- reusable command sequences via `Justfile`
+- lightweight onboarding docs for Codex behavior
+
+## Recommendations
+
+- Keep environment setup documented in `docs/`.
+- Separate repo updates from user-profile updates.
+- Validate environment commands after each phase.
+- Use conservative defaults and escalate only as needed.

.codex/skills/configure-codex/references/rules-default.md

@@ -0,0 +1,47 @@
+# `.codex/rules/default.rules` guidance
+
+## Principles
+
+- Keep permissions scoped to the project workflow.
+- Prefer minimal, explicit commands.
+- Ask before writing any potentially sensitive settings.
+
+## Typical command families
+
+- `uv`: Python install/test/runtime commands
+- `just`: repeated repo task orchestration
+- `pnpm`: node tooling for web apps
+- `gh`: GitHub workflows and issue/pr management
+- `glab`: GitLab/GLab workflow parity where used
+
+## Process
+
+- Propose a diff, confirm with user, then apply.
+- Re-check the rule set after each commit boundary.
+## Example `prefix_rule` syntax
+
+```python
+prefix_rule(
+    pattern = ["uv", "sync"],
+    decision = "allow",
+    justification = "Allow project dependency sync outside sandbox",
+    match = [
+        "uv sync",
+        "uv sync --locked",
+    ],
+    not_match = ["uv run sync"],
+)
+```
+
+Use `match` and `not_match` as inline rule tests so malformed patterns fail fast when the rule file is loaded.
+
+## Validate the rules file
+
+Run a rule check after updating `default.rules`:
+
+```bash
+codex execpolicy check --pretty --rules .codex/rules/default.rules -- uv sync
+```
+
+Use the same command for any command you changed in the allow list.
+

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

@@ -0,0 +1,40 @@
+---
+name: init-repo
+description: "Initialize a new repo with a fast, testable, documented, agent-friendly setup using zach-stack defaults."
+---
+
+# Init Repo
+
+Use this skill when a user asks to start a new project or bootstrap an empty repository.
+
+## Workflow
+
+If required dependencies are missing in this environment, bootstrap them first:
+
+- `$install-skills https://github.com/openai/skills/tree/main/skills/.custom/zach-stack`
+- `$install-skills https://github.com/openai/skills/tree/main/skills/.custom/configure-codex`
+
+1. Capture constraints and ask clarifying questions only if ambiguous.
+2. Choose a stack profile: web, python, visualization, or mixed.
+3. Create a phase-1 scaffold that is minimal but complete:
+   - `docs/` with setup and file map starter.
+   - `Justfile` with repeatable agent commands.
+   - Testing skeleton (unit + at least one integration check).
+   - Linting/pre-commit baseline for selected stack.
+   - Optional `.codex/rules/default.rules` proposal via `configure-codex`.
+4. Add technology-specific defaults from `zach-stack`:
+   - web defaults (framework-light vs lightweight React)
+   - Python defaults (`uv`)
+   - workspace structure if mixed.
+5. Define the first milestone commit boundary.
+
+## Guardrails
+
+- Keep `init-repo` incremental: prefer Phase 1 completion over full build-out.
+- Default to minimal files and explain what is deferred.
+- Never write sensitive agent/environment rules without explicit user confirmation.
+
+## References
+
+- Use `references/new-repo-runbook.md` for scaffold templates and command defaults.
+- Use `../zach-stack` for stack-specific decisions.

.codex/skills/init-repo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Init Repo"
+  short_description: "Bootstrap a new repo with testable and agent-friendly defaults."
+  default_prompt: "Use $init-repo to scaffold a new repository with zach-stack conventions."

.codex/skills/init-repo/references/new-repo-runbook.md

@@ -0,0 +1,21 @@
+# New repo runbook
+
+## Phase 1 scaffold (minimum)
+
+- Create `docs/` and add a compact onboarding file.
+- Add `Justfile` with build/test/lint commands.
+- Add dependency/tool defaults for selected stack (`pnpm` for web, `uv` for Python).
+- Add testing skeleton for targeted unit and integration coverage.
+- Add workspace/docs conventions in notes for future phases.
+
+## Recommended first tasks
+
+- Choose stack from `zach-stack` profiles.
+- Add contributor-level checklist for tests and docs updates.
+- Add a clean rollback point before changing environment/config files.
+
+## Suggested outputs by stack
+
+- Web: Tailwind baseline + lightweight project setup + test/check commands.
+- Python: `pyproject.toml`/`uv` convention + basic test command.
+- Mixed: two-phase plan with clear module boundaries and shared-data workspace notes.

.codex/skills/zach-stack/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: zach-stack
+description: "Define opinionated conventions for testable, well-documented, agent-friendly repos. Use for stack selection and application defaults."
+---
+
+# Zach-Stack
+
+Use this skill when asked to define or apply a preferred stack for a new/existing project.
+
+## Purpose
+
+`zach-stack` is the compact decision source for:
+- project scaffolding defaults
+- tooling conventions
+- test strategy expectations
+- docs/lifecycle defaults
+- Codex-friendly repository structure
+
+## When to use
+
+- before or during `init-repo`
+- during `agentify-repo` as the target conventions
+- when a team member asks for your preferred stack defaults
+
+## Core rules (high signal)
+
+- **Minimal web by default**: prefer plain HTML/CSS/JS when requirements are simple.
+- **Dynamic web**: choose a lightweight React setup when needed for stateful interactions.
+- **Complex static sites**: prefer Eleventy.
+- **CSS**: default to Tailwind.
+- **Python work**: use `uv` for package management and virtual environments.
+- **Workspaces**: prefer workspace-based organization for multi-module projects.
+- **CLI stack**: prefer **Typer** for new CLIs; use **Click** when existing codebases already use it.
+- **Testing**: add targeted unit tests and at least one integration/acceptance layer.
+- **Frontend checks**: include automated checks that cover real user workflows.
+- **Playwright path**: use Playwright CLI for exploration and flow debugging; use Playwright-driven E2E where applicable.
+- **Visualization**: prefer Streamlit + Plotly for analytics UI.
+- **Project shape for shared data**: use a dedicated workspace/module for data, plus workspace boundaries for Streamlit/compute when needed.
+- **Standalone scripts**: keep CLIs standalone with minimal dependencies and explicit script-level dependency boundaries; keep CLIs minimally scoped.
+- **Docs as source of truth**: every project must have `docs/` and keep it current with code changes.
+- **Automation**: include `Justfile` in most repos for repeatable agent tasks.
+- **Pre-commit**: always define pre-commit via project-native tooling (`pnpm` or `uv`).
+
+## Process
+
+1. Ask for project intent: web app, python service, data app, or mixed.
+2. Select a minimal stack from these preferences.
+3. Confirm constraints that override defaults (security, infra, legacy platform).
+4. Apply only what is relevant for the project phase.
+
+## References
+
+- `references/web.md` for web defaults, CSS, and Playwright use.
+- `references/python.md` for UV, workspace, and Python conventions.
+- `references/testing.md` for test structure expectations.
+- `references/docs.md` for living docs patterns.
+- `references/workspaces.md` for shared workspaces in mixed stacks.
+- `references/resources.md` for external source references.

.codex/skills/zach-stack/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Zach Stack"
+  short_description: "Opinionated stack defaults for agent-friendly repos."
+  default_prompt: "Use $zach-stack to define technology and workflow defaults for the repo."

.codex/skills/zach-stack/references/docs.md

@@ -0,0 +1,19 @@
+# Documentation conventions (`zach-stack`)
+
+## Minimum
+
+- Every repo must include `docs/`.
+- Docs should include a file index/structure map and quick update points.
+- Keep docs updated as part of meaningful code changes.
+
+## Practical expectations
+
+- Maintain short-lived markdown docs that stay current with code.
+- Include architecture and setup notes in `docs/` for onboarding.
+- Keep one canonical source-of-truth for setup commands and developer workflows.
+- Add a short, versioned list of files and responsibility in `docs/file-map.md` (or equivalent).
+
+## Docs quality and checks
+
+- Use docs linting where practical to catch stale references.
+- Treat docs quality as part of completion criteria before considering a change done.