AGENTS.md@development · diff
git:20261014.72d6c82 to git:20261115.1fb19c9
6 added, 0 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# 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
+ - `council`: before finalizing a plan, deliberate with the other agent CLIs
+ installed on the machine for a set number of read-only review turns
+ (vendored from kitze/council under MIT)
- `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.
+ - For council deliberations, members run read-only and never touch the repo,
+ and nothing is implemented unless the user asked for execution after
+ planning. Keep `development/skills/council/LICENSE` with the skill.
- Do not manually restore removed development skills in top-level `skills/`.
Run `npm run sync` so the generated mirror matches `development/skills/`.