From f0c6cbf49f8f94bb9dbbb2f881383d3599077ef7 Mon Sep 17 00:00:00 2001 From: bisco Date: Fri, 20 Mar 2026 19:01:17 +0100 Subject: [PATCH] chore: add Codex and agent workflow foundation --- .agents/skills/task-closeout/SKILLS.md | 20 +++ .codex/agents/docs_researcher.toml | 16 ++ .codex/agents/implementer.toml | 18 +++ .codex/agents/reviewer.toml | 18 +++ .codex/config.toml | 7 + .editorconfig | 18 +++ .gitignore | 65 ++++++++ AGENTS.md | 211 +++++++++++++++++++++++++ Makefile | 4 + docs/MACHINE_SETUP.md | 37 +++++ docs/TASK_TEMPLATE.md | 25 +++ docs/WORKFLOW.md | 33 ++++ scripts/doctor.sh | 18 +++ 13 files changed, 490 insertions(+) create mode 100644 .agents/skills/task-closeout/SKILLS.md create mode 100644 .codex/agents/docs_researcher.toml create mode 100644 .codex/agents/implementer.toml create mode 100644 .codex/agents/reviewer.toml create mode 100644 .codex/config.toml create mode 100644 .editorconfig create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 Makefile create mode 100644 docs/MACHINE_SETUP.md create mode 100644 docs/TASK_TEMPLATE.md create mode 100644 docs/WORKFLOW.md create mode 100644 scripts/doctor.sh diff --git a/.agents/skills/task-closeout/SKILLS.md b/.agents/skills/task-closeout/SKILLS.md new file mode 100644 index 0000000..7d544a8 --- /dev/null +++ b/.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. \ No newline at end of file diff --git a/.codex/agents/docs_researcher.toml b/.codex/agents/docs_researcher.toml new file mode 100644 index 0000000..5805e25 --- /dev/null +++ b/.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. +""" \ No newline at end of file diff --git a/.codex/agents/implementer.toml b/.codex/agents/implementer.toml new file mode 100644 index 0000000..47856ef --- /dev/null +++ b/.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. +""" \ No newline at end of file diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 0000000..8018b1a --- /dev/null +++ b/.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. +""" \ No newline at end of file diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..ce63738 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..06c7328 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c7ba32f --- /dev/null +++ b/.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/ \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3b8dbda --- /dev/null +++ b/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. \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..40c00be --- /dev/null +++ b/Makefile @@ -0,0 +1,4 @@ +.PHONY: doctor + +doctor: + bash scripts/doctor.sh \ No newline at end of file diff --git a/docs/MACHINE_SETUP.md b/docs/MACHINE_SETUP.md new file mode 100644 index 0000000..29f0426 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/TASK_TEMPLATE.md b/docs/TASK_TEMPLATE.md new file mode 100644 index 0000000..bef782f --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md new file mode 100644 index 0000000..daacea4 --- /dev/null +++ b/docs/WORKFLOW.md @@ -0,0 +1,33 @@ +# Workflow + +## Branch policy + +Protected branches: +- main +- develop + +Normal task flow: +1. checkout develop +2. create feature/ +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 \ No newline at end of file diff --git a/scripts/doctor.sh b/scripts/doctor.sh new file mode 100644 index 0000000..4718ba4 --- /dev/null +++ b/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." \ No newline at end of file