pygienium/AGENTS.md

AGENTS.md

Pygienium is a pi extension: code-hygiene checks that scan a target with isolated sub-agent sessions (analysis), optionally apply fixes, then verify artifacts. Sub-agents are defined as markdown in agents/*.md (YAML frontmatter: name, allowedTools; body = system prompt).

Commands

• bun run typecheck — tsc --noEmit on src/
• bun test — full suite (bun test)

Layout

• src/checks/ — check definitions; self-register on import (registerCheck)
• src/agent-runner.ts — spawns sub-agent sessions; runner injectable (setAgentRunner), tests use fakeAgentRunner (no real model calls)
• src/commands.ts — slash-command handlers, exported for direct test invocation with a stub PygieniumCtx
• tests/ — bun tests; stub ctx with { cwd, mode: "print", hasUI: false, ui: undefined } as PygieniumCtx
• port-to-omp.mjs — regenerates the self-contained omp port (see commit process)

Conventions

• Checks: gate (skip reason), buildScanTask, optional buildFixTask, optional verify. Scan tasks embed !write/!echo lines as deterministic fallback for the fake runner.
• Sub-agent sessions must be pinned to the invoking session's model: thread ctx.model through PygieniumCtx → run options → AgentTaskOptions.model → createAgentSession({ model }).
• Keep files modular; no compatibility shims.

Commit process (IMPORTANT)

Commits are gated by the pre-commit hook (enable: git config core.hooksPath .githooks). It regenerates the omp port into a temp dir and typechecks it — exactly what CI runs. A failing hook blocks the commit; never bypass with --no-verify.

port-to-omp.mjs rewrites source via exact-string matchers (FILE_RULES). Editing these files requires keeping the matching ops in sync or the port regeneration throws and the commit is blocked:

• src/index.ts — removes mode: ctx.mode from the pygieniumCtx literal
• src/commands.ts — removes mode from the PygieniumCtx Pick; swaps ctx.mode for ctx.hasUI in print
• src/agent-runner.ts — swaps the SDK import + loader for the omp SDK's createAgentSession options (toolNames, systemPrompt, agentRegistry, …)
• src/agents.ts — find → glob

After touching any of those, run bun port-to-omp.mjs --out <tmp> and (cd <tmp> && bun run typecheck) before committing; the hook does the same.