chore: add Codex and agent workflow foundation

.agents/skills/task-closeout/SKILLS.md

@@ -0,0 +1,20 @@
+---
+name: task-closeout
+description: Use this skill when a development task is complete and needs a clean closeout: commit, docs check, merge target confirmation, and summary.
+---
+
+When this skill is used:
+
+1. Verify the current branch is a task branch, not main or develop.
+2. Verify the task scope was respected.
+3. Check whether docs or tests need updates.
+4. Prepare a clean commit message.
+5. Confirm the intended merge target.
+6. Summarize:
+   - what changed
+   - what was not changed
+   - what remains open
+7. Stop.
+
+Do not perform release actions.
+Do not merge into main.

.codex/agents/docs_researcher.toml

@@ -0,0 +1,16 @@
+name = "docs_researcher"
+description = "Documentation-focused agent for workflow consistency and external doc verification."
+sandbox_mode = "read-only"
+developer_instructions = """
+Focus on documentation and process consistency.
+
+Check:
+- README accuracy
+- setup instructions
+- workflow docs
+- branch policy docs
+- task template clarity
+
+When external docs matter, verify them before concluding.
+Do not make runtime or product changes unless explicitly asked.
+"""

.codex/agents/implementer.toml

@@ -0,0 +1,18 @@
+name = "implementer"
+description = "Implementation-focused agent for small, targeted, repository-safe changes."
+developer_instructions = """
+Work like a disciplined implementation engineer.
+
+Follow the repository workflow in AGENTS.md exactly.
+Stay narrowly scoped to the requested task.
+Do not broaden scope.
+Prefer the smallest safe change.
+Update tests and docs when behavior changes.
+Always report:
+- branch strategy
+- files changed
+- commit message
+- merge target
+
+Do not work directly on main or develop.
+"""

.codex/agents/reviewer.toml

@@ -0,0 +1,18 @@
+name = "reviewer"
+description = "Read-only reviewer focused on correctness, regressions, workflow drift, and missing tests."
+sandbox_mode = "read-only"
+developer_instructions = """
+Review like an owner.
+
+Prioritize:
+- correctness
+- regressions
+- branch/workflow mistakes
+- documentation drift
+- missing tests
+- release-readiness blockers
+
+Lead with concrete findings.
+Avoid style-only comments unless they hide a real risk.
+Do not propose broad redesign unless explicitly requested.
+"""

.codex/config.toml

@@ -0,0 +1,7 @@
+project_root_markers = [".git"]
+project_doc_fallback_filenames = ["AGENTS.md", "TEAM_GUIDE.md"]
+project_doc_max_bytes = 65536
+
+[agents]
+max_threads = 4
+max_depth = 1

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.gitignore

@@ -0,0 +1,65 @@
+# OS / editor
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+.idea/
+.vscode/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.python-version
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Type check / lint caches
+.mypy_cache/
+.ruff_cache/
+.pyre/
+
+# Django
+db.sqlite3
+db.sqlite3-journal
+media/
+staticfiles/
+local_settings.py
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Logs / pid
+*.log
+*.pid
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Codex / agents local-only state
+.codex/tmp/
+.codex/cache/
+
+# Project runtime data
+data/
+tmp/

AGENTS.md

@@ -0,0 +1,211 @@
+# AGENTS.md
+
+## Scope of this repository
+
+This repository is in **phase 0**.
+
+The goal of this phase is to define:
+- how development with Codex and custom agents works
+- how repository workflow works
+- how tasks are executed and closed
+- how the project remains portable across machines
+
+This phase is **not** for deciding the product architecture or implementing application features.
+
+Agents must optimize for:
+- repeatability
+- portability
+- low ambiguity
+- clean branch discipline
+- durable project instructions stored in the repository
+
+---
+
+## Ground rules
+
+- Do not work directly on `main`
+- Do not work directly on `develop`
+- Use task branches created from `develop`
+- Merge completed task branches back into `develop`
+- Do not rewrite history
+- Do not silently stash work and continue elsewhere
+- Do not broaden task scope unnecessarily
+- Stop after the requested task is complete
+
+---
+
+## Default Git workflow
+
+Unless explicitly overridden by the user, use this branch model:
+
+- `main` = stable production branch
+- `develop` = integration branch
+- `feature/*` = normal development work
+- `release/*` = release stabilization
+- `hotfix/*` = urgent production fixes
+
+For normal implementation tasks:
+1. checkout `develop`
+2. create a `feature/*` branch from `develop`
+3. complete the task on that branch
+4. commit the work
+5. merge the feature branch back into `develop`
+6. stop
+
+If a large multi-step initiative needs an umbrella integration branch, the user must explicitly approve it and the branch must be documented in `docs/WORKFLOW.md`.
+
+---
+
+## Required behavior for Codex tasks
+
+For any coding task, agents should respond in this order:
+
+1. confirm branch strategy
+2. state which branch will be used
+3. list the files to change
+4. explain the design briefly
+5. make the requested changes
+6. update tests/docs when relevant
+7. provide the commit message used
+8. confirm the merge target
+9. stop
+
+If a remote fetch/pull fails, continue using local branch state and say so explicitly.
+
+---
+
+## Repository-first portability rules
+
+Assume development may happen from different machines.
+
+Anything durable must live in the repository, not only in local Codex config.
+
+Put stable project behavior in:
+- `AGENTS.md`
+- `.codex/config.toml`
+- `.codex/agents/*.toml`
+- `.agents/skills/*`
+- `docs/*.md`
+
+Do not rely on undocumented local conventions.
+
+---
+
+## What belongs in local machine config vs repository
+
+### Must be repository-owned
+- task workflow
+- branch strategy
+- coding process
+- agent roles
+- repo-specific instructions
+- reusable task-closing workflows
+- machine setup instructions
+- test execution instructions
+
+### Must stay local
+- authentication
+- personal shell aliases
+- personal editor preferences
+- secrets
+- API keys
+- machine-specific paths unless documented as examples only
+
+---
+
+## Agent role boundaries
+
+### implementer
+Use for:
+- targeted implementation work
+- small safe refactors
+- wiring code/tests/docs for a defined task
+
+Must avoid:
+- broad redesign without approval
+- speculative cleanup outside the task
+
+### reviewer
+Use for:
+- correctness review
+- regression risk review
+- test gap review
+- release-readiness review
+
+Must avoid:
+- making code changes directly unless explicitly asked
+
+### docs_researcher
+Use for:
+- documentation verification
+- framework/API behavior checking
+- repo docs consistency checks
+
+Must avoid:
+- changing runtime behavior unless explicitly asked
+
+---
+
+## Skills philosophy
+
+Use skills for repeatable repository workflows, not for one-off prompts.
+
+Preferred early skill examples:
+- task closeout
+- branch hygiene
+- release checklist
+- docs consistency check
+
+Keep skills narrow and explicit.
+
+---
+
+## Testing discipline
+
+When a task changes behavior, update or add tests where relevant.
+
+If test tooling is not available in the runtime image, document the correct dev/test path instead of pretending tests ran.
+
+Never claim tests passed unless they were actually executed.
+
+---
+
+## Documentation discipline
+
+Whenever behavior changes, update docs if relevant.
+
+At minimum, keep aligned:
+- `README.md`
+- `docs/WORKFLOW.md`
+- `docs/MACHINE_SETUP.md`
+- `docs/TASK_TEMPLATE.md`
+
+Do not let docs drift from actual workflow.
+
+---
+
+## Out of scope in phase 0
+
+Do not decide yet:
+- final application architecture
+- final domain model
+- runtime services beyond workflow tooling
+- database technology
+- ingestion strategy
+- feature list
+
+If a task drifts into product design, stop and ask for a separate explicit decision.
+
+---
+
+## Preferred task style
+
+Make the smallest safe change that solves the requested process problem.
+
+Avoid:
+- unnecessary abstraction
+- premature architecture
+- speculative optimization
+- introducing tools that are not yet justified
+
+This phase is about building a clean development method first.

Makefile

@@ -0,0 +1,4 @@
+.PHONY: doctor
+
+doctor:
+	bash scripts/doctor.sh

docs/MACHINE_SETUP.md

@@ -0,0 +1,37 @@
+# Machine Setup
+
+## Goal
+
+Bring a new machine to a usable Codex development state with minimal local-only setup.
+
+## Local-only prerequisites
+
+Not stored in the repo:
+- Codex authentication
+- personal shell setup
+- secrets/API keys
+- local editor preferences
+
+## Repository bootstrap
+
+1. Clone the repository
+2. Checkout `develop`
+3. Read:
+   - AGENTS.md
+   - docs/WORKFLOW.md
+   - docs/TASK_TEMPLATE.md
+4. Ensure Codex can see:
+   - AGENTS.md
+   - .codex/config.toml
+   - .codex/agents/*
+   - .agents/skills/*
+
+## Validation checklist
+
+A machine is considered ready when:
+- repo is cloned
+- correct branch is checked out
+- Codex authentication is working
+- AGENTS.md is present at repo root
+- .codex/config.toml is present
+- task branches can be created from develop

docs/TASK_TEMPLATE.md

@@ -0,0 +1,25 @@
+# Task Template
+
+Use this structure for Codex implementation tasks.
+
+## Required opening
+
+- confirm branch strategy
+- name the branch to use
+- state whether remote update succeeded or local state is being used
+
+## Required execution structure
+
+1. files to change
+2. short design explanation
+3. code/doc/test changes
+4. commit message
+5. merge target
+6. stop
+
+## Constraints
+
+- no work on main
+- no work on develop
+- no history rewrite
+- no broadening scope without approval

docs/WORKFLOW.md

@@ -0,0 +1,33 @@
+# Workflow
+
+## Branch policy
+
+Protected branches:
+- main
+- develop
+
+Normal task flow:
+1. checkout develop
+2. create feature/<task-name>
+3. implement the task
+4. commit changes
+5. merge feature branch into develop
+6. delete feature branch when appropriate
+
+## When to use an umbrella branch
+
+Use an umbrella branch only for a large coordinated effort that spans multiple dependent feature branches.
+
+If used, document:
+- why it exists
+- its exact name
+- which child branches merge into it
+- when it is expected to merge back into develop
+
+## Task discipline
+
+Each task should:
+- have one clear goal
+- have one task branch
+- end with a commit and merge target confirmation
+- not silently include unrelated cleanup

scripts/doctor.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "== Repo doctor =="
+
+test -f AGENTS.md && echo "AGENTS.md: OK" || { echo "AGENTS.md: MISSING"; exit 1; }
+test -f .codex/config.toml && echo ".codex/config.toml: OK" || { echo ".codex/config.toml: MISSING"; exit 1; }
+test -d .codex/agents && echo ".codex/agents: OK" || { echo ".codex/agents: MISSING"; exit 1; }
+test -d docs && echo "docs/: OK" || { echo "docs/: MISSING"; exit 1; }
+
+branch="$(git rev-parse --abbrev-ref HEAD)"
+echo "Current branch: ${branch}"
+
+if [[ "${branch}" == "main" || "${branch}" == "develop" ]]; then
+  echo "Warning: create a task branch before making changes."
+fi
+
+echo "Doctor completed."