AGENTS.md

thesisbug2 is an AI-agent framework for Traditional Chinese academic coursework. It is mounted as a git submodule at .framework/ inside one private repository per course. This repository is the framework only; it never contains coursework.

Current state

docs/DESIGN.md is the source of truth for the architecture and for what is decided. Read it before proposing or making changes.

What exists so far:

• The 15 shared agent skills live in .agents/skills/, rewritten for the course layout: unit paths are written <unit>/…, shared sources library/…, and every command is ./fw <command>. The Claude-only self-inject recipe is an optional note under docs/integrations/, outside shared discovery. The port was audited for public use (thesis-specific values replaced with slots to fill; the font ships with its OFL text).
• scripts/fw and the commands behind it work: unit-init, build, apply-edits, check-bib, check-citations, check-zh-variants, check-progress, check-login, check-contrast, deck-refresh, deck-notes, deck-text, deck-compile, deck-motion-pick, storyboard-review, log, score-bib, count-zh, lint-readability, plantuml2svg, yt2sub. Templates live in assets/templates/<type>/; they name framework files with the token {{FW}}, which build and unit-init replace with the unit's relative path to the framework. scripts/_paths.py is the only place that knows the course layout (course root, nearest WORK.json, library/); a script that builds such a path itself is a bug. A script that needs third-party packages declares them in a PEP 723 header and fw runs it under uv; the rest use the standard library only.
• install.sh and scripts/course-init.py create a course: fields → local repo → shallow .framework/ submodule → skeleton from assets/course-skeleton/ → agent directives (pointer files, skill symlinks) → private GitHub repo. course-init.py uses only the standard library because install.sh runs it before anything is installed; --no-github --framework-url <local path> exercises it offline (set XDG_CONFIG_HOME to a scratch directory so the test neither reads nor writes the real ~/.config/thesisbug2/config.ini). The full path — published install.sh, private repo creation, topic, and a fresh git clone --recurse-submodules of the result — was verified on 2026-09-19 by creating a real course.
• refs (where, promote) and refs-snapshot are in. refs-snapshot push has run against a real course Release and pull has not; offline tests with a stand-in gh cover help never reaching a subcommand, push keeping manifest rows whose original is absent locally, and forget; promote is covered by scratch-repo tests (plain promote, duplicate-fetch merge, refusal on differing transcripts). The four protocol files under assets/templates/ are ported with all personal context removed — identity, institution, and field come from the course's COURSE.md. Skills already name some of these (./fw build, ./fw refs promote), so do not report one as run until ./fw help lists it. The roadmap in docs/DESIGN.md gives the order.

To try a script without a real course, make a scratch directory with units/<name>/WORK.json, symlink this repo in as .framework, and add the two-line fw shim (exec "$(dirname "$0")/.framework/scripts/fw" "$@").

todo, decision, and workflow are an opt-in JSON workflow experiment for course units. Existing units and other projects are not migrated automatically; general context cleanup uses their existing files and the optional external context-cleanup skill.

Skill evals

flow-check, source-kit, and safe-edit carry evals/evals.json (four, three, and three scenarios respectively: a query, fixture files, expected behaviours) and invented fixtures with planted defects, described in each evals/fixtures/README.md. There is no model-eval runner. To check a skill after editing it, build a scratch course repo, copy the fixture in as units/01-paper-eval/, copy .agents/skills/ in without any evals/ directory (leaving it in hands the agent the answers), give a fresh-context agent only the query, and compare what it did — and what git status in the scratch repo shows — with expected_behavior. Add a scenario when a real session shows a skill failing, rather than guessing at failures in advance.

uv run --no-project -m unittest discover -s tests -v runs the offline regression suite. Installer cases cover agent-free setup, slug handling, recursive clones, and preserving coursework during updates; workflow cases cover revision retention, concurrent/stale writes, migration, bounded queries, recovery, and repeated handoffs without new history. Tests use temporary repos and isolated configuration, and CI runs them on macOS and Ubuntu.

The predecessor is thesisbug-template (private), usually checked out beside this repo at ../thesisbug-template. Skills, scripts, and templates are ported from there.

Rules for working in this repository

• Every agent session in a course repo starts with ./fw update from the course root, because the thesisbug2 submodule must receive current shared instructions and tools before coursework begins. Then re-read .framework/docs/AGENT-GUIDE.md. This authorizes a local commit of the framework pin only, not a push; if updating fails, report the failure and continue with the available checkout without resetting, stashing, or discarding local work. This framework repo itself has no .framework/ submodule and follows its normal main-branch sync instead.
• Keep shared workflows agent agnostic. AGENTS.md is canonical; vendor files only point to it, and shared skills describe capabilities rather than a vendor's tool names or home paths, because every agent must be able to follow the same procedure. Optional integrations must state their prerequisites and a missing-capability outcome; course creation and framework commands never launch an AI CLI implicitly.
• Image generation uses Codex as an explicit exception, because it is currently the maintainer's stable image backend; the host agent can still be any agent. Prefer Codex's native image tool when available, otherwise use the discovered genimage-img2 Codex wrapper, and report a missing backend instead of silently choosing another image provider.
• This repo is public; the predecessor is private. Before copying anything in, clear it against docs/DESIGN.md § Audit required before each port. Personal context, coursework content, thesis-specific wording, and fonts or images without redistribution rights stay out. Port by copying files into new commits; never import the predecessor's git history, because its work branches contain private coursework.
• Keep coursework paths out of the framework. Framework code locates a unit by walking up to the nearest WORK.json and reads shared sources from the course's library/. A hard-coded work/ path is a bug here.
• Update the design document with the change. When a decision in docs/DESIGN.md changes, edit the document in the same commit, so the design and the code cannot drift apart. Rewrite the affected contract in place; session narratives and individual test-run results belong in commit messages, because accumulating them in project context buries the current rules. Review context-file diffs for this during workflow-tool development too.
• Explain rules when you add them. An instruction added to a skill, a protocol, or this file carries its reason in the same sentence. Current models follow instructions literally and generalise from the reason; a bare prohibition gets applied too broadly or too narrowly.
• Skill descriptions stay at roughly 300–500 characters, third person, stating what the skill does and when to use it. Every agent loads all descriptions at startup, and long ones get truncated at a point the author did not choose. The hard limit is 1,024.
• Diagrams are Mermaid in fenced blocks inside the Markdown, so the rendered diagram cannot drift from its source.

Authorizations

• Jev calls for the deck pickers (./fw deck-motion-pick and the deck-pick planned in DESIGN.md § Open questions) are acknowledged by the maintainer (2026-10-14, "jev可以用"): an agent may pass --ack for a run on a storyboard without asking again. Run the estimate first, report the tokens used after, and keep each run to one storyboard; the runner caches identical requests, so a replay is free. Any other Jev use still needs the maintainer's ack per call (jev-decide skill).