From be427a760764f3db328c6102fbb9761d24baef7a Mon Sep 17 00:00:00 2001 From: Mads Lorentzen <50207393+MadsLorentzen@users.noreply.github.com> Date: Wed, 15 Jul 2026 22:34:10 +0200 Subject: [PATCH] docs: codify the runtime policy - Claude Code first, runtime forks welcome (#163) Writes down the architecture decision from the #78 discussion (2026-07-15): Claude Code is the reference runtime; other agent runtimes are supported at the edges via the portable portal skills in .agents/skills/, the root AGENTS.md signpost, and thin-pointer community forks. Per-runtime command trees stay in forks for the same reason market portals do. README gets one line in Prerequisites; CONTRIBUTING gets the policy section beside the market-skills rule it mirrors, including the explicit revisit conditions. Co-authored-by: Claude Fable 5 --- CONTRIBUTING.md | 14 ++++++++++++++ README.md | 2 +- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 91b5318..6a4d89f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,6 +45,20 @@ Reviews here are empirical. Bug reports are reproduced on master before the fix Market-specific skills are genuinely valuable - they just live in forks, where their maintainers can test them and their users can find them. +## Porting to another AI runtime? Forks too + +Claude Code is the reference runtime: it is what the maintainer runs daily and what every methodology change is verified on. A parallel command tree for another runtime (Codex, Antigravity, Gemini CLI, ...) would ship untested on every change - CI cannot run those harnesses - and each accepted runtime makes the next one harder to refuse. It is the same arithmetic that keeps market-specific portals in forks. + +What upstream maintains for other runtimes instead: + +- The portal search skills in `.agents/skills/` use the portable Agent Skills format (`SKILL.md` per portal) and are auto-discovered by Codex and Antigravity today. +- The root `AGENTS.md` points any agent at the canonical workflow specs and the profile entry point. +- Framework instruction files carry `framework_version` markers, so a runtime fork can track methodology changes precisely (`python3 tools/check_upstream_updates.py`). + +Announce your runtime fork in the pinned [Community forks & adaptations](https://github.com/MadsLorentzen/ai-job-search/discussions/78) discussion and it gets listed alongside the market adaptations. The proven shape is a thin pointer: reference the specs here instead of copying them, so upstream improvements reach your fork on rebase. + +This is a decision, not a dogma: if cross-runtime standards mature to the point where these specs run unmodified elsewhere, or the community's center of gravity moves to runtime forks, the trade-off gets re-evaluated. Background: the architecture thread in [Community forks & adaptations](https://github.com/MadsLorentzen/ai-job-search/discussions/78). + ## Practical notes - **Portal-skill contract**: `search`/`detail` commands, `--format json|table|plain`, stderr JSON errors with exit 1, backoff on 429/5xx, zero runtime dependencies by default. See `/add-portal`'s spec and `linkedin-search` as the reference implementation. diff --git a/README.md b/README.md index 594520d..2515d5b 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ The framework encodes career guidance best practices, including structured evalu ## Prerequisites -- [Claude Code](https://claude.com/claude-code) (CLI) +- [Claude Code](https://claude.com/claude-code) (CLI). Using a different agent tool (Codex, Antigravity, Gemini CLI)? Start at [`AGENTS.md`](AGENTS.md) - the portal search skills work there out of the box, and [community forks](https://github.com/MadsLorentzen/ai-job-search/discussions/78) adapt the full workflow. - Python 3.10+ - [Bun](https://bun.sh) (for job search CLI tools) - LaTeX distribution with `lualatex` and `xelatex`: [TeX Live](https://tug.org/texlive/), [MacTeX](https://tug.org/mactex/), [TinyTeX](https://yihui.org/tinytex/), or [MiKTeX](https://miktex.org/). The CV compiles with `lualatex` (pdflatex often fails on modern MiKTeX installs with `fontawesome5` font-expansion errors); the cover letter compiles with `xelatex` because `cover.cls` requires `fontspec`. If using a minimal TeX install such as TinyTeX or BasicTeX, install the extra packages listed in [SETUP.md](SETUP.md#minimal-tex-install-tinytexbasictex).