AGENTS.md

This plugin contains development workflow skills for maintaining repo-facing agent context.

Structure

• .codex-plugin/plugin.json: plugin manifest
• skills/*/SKILL.md: development workflow skills

Source Of Truth

• development/skills/ is the source of truth for this plugin.
• Repository-wide mirrored skills/ copies are synced via npm run sync.
• Do not manually duplicate edits into top-level skills/ unless sync tooling is unavailable.

Current Skill Surface

• cli-design: design, build, or review command-line interfaces using the Command Line Interface Guidelines from clig.dev
• codebase-landing-copy: write product landing-page copy grounded in capabilities that are proven by shipped code
• context-file-tuneup: audit and rewrite CLAUDE.md / AGENTS.md files so they stay short, specific, and grounded in the repo
• course-notes: turn photos of lecture notes into standalone, source-checked study notes as a print-ready PDF, pitched at the reader's familiarity level
• feature-map: build a repo-local verification skill listing each user-facing feature, how to reach and drive it, and what to observe
• decision-records: write or update decision and implementation-plan records (ADRs) in a repo's records directory, keep the registry table in sync, and preserve history through amendments and supersession
• github-pr-fixup: check out an existing GitHub PR branch, address active unresolved review comments and failing CI, then push fixes back to that PR
• whiteboard: map a codebase's architecture and design rationale, then quiz the user whiteboard-defense style on flows, trade-offs, and failure modes
• github-self-hosted-runner: install, register, namespace, verify, or remove GitHub Actions self-hosted runners on Linux under systemd or macOS under launchd
• oss-marketing: sharpen open source README/public-doc positioning for first-visit clarity, launch copy, and visitor-to-user conversion
• oss-repo-readiness: audit and prepare a GitHub repo for open source release, emphasizing first-run and first-contribution developer experience
• session-log-audit: mine local agent session logs (Claude Code, Pi, Codex) for papercuts in a project the user builds with agents, then rank the fixes
• technical-manual: write a book-length, print-ready PDF manual about a format, protocol, library, or system, grounded in its pinned spec and source
• verify-bug: decide whether claimed bugs are real through an isolated Prover/Skeptic/Referee hearing, with repro tests in throwaway worktrees

Workflow Policy

• Keep context-file changes evidence-backed: inspect manifests, CI, docs, and repo structure before recommending edits.
• For user-facing context rewrites, preserve the skill's inspect -> audit -> propose -> confirm -> apply loop unless the user has explicitly asked for direct repo-doc edits here.
• For PR fixups, work on the existing PR branch. Do not open a replacement PR, do not resolve review threads unless asked, and ignore resolved or outdated review comments.
• For session log audits, collect receipts before you diagnose. Work through the numbered phases in order and meet each gate. Treat what the user suspects as a hypothesis to test, not as a finding.
• For whiteboard maps, never invent design rationale. Tag rationale claims with evidence, keep defense records local under .map/, and never modify the working tree. /whiteboard docs writes only to a worktree branch, keeps source edits to a comments-only commit, and pushes only on confirmation.
• For feature maps, record only drive steps observed to work, drive local or development environments only, never write secret values, and write only inside the generated skill directory.
• For bug verification, never touch the working tree (repros run only in a git worktree under .verify/), never fix code or open issues, and post verdicts to GitHub only after the user confirms each post.
• For self-hosted runners, resolve the runner account instead of assuming a user or home directory, keep one namespaced instance per target, treat tokens as secrets that never reach a file that persists, and confirm no job is running before you stop, replace, or delete an instance.
• For decision records, the registry README.md is the contract. Read it and the related records before writing. Never rewrite an existing record's history; add a dated amendment or a superseding record instead. Ask before bootstrapping a records directory in a repo that has none.
• For technical manuals, write no prose before the research folder, captures, and outline exist. Every claim traces to a pinned source or captured artefact, figures are drawn from captures, and unverifiable claims are cut or marked unverified.
• For course notes, never add from memory: cite the course's slides, study guide or paper, and compute numbers with check scripts. Keep the book standalone (no "you", no quotes from or mentions of the original notes); ask the student about their own pages in the conversation, one question at a time. Ask for the familiarity level (1–5) before writing.
• Do not manually restore removed development skills in top-level skills/. Run npm run sync so the generated mirror matches development/skills/.