3e561a3f9f
* refactor(skill): shorten hassio-addon-workflow via progressive disclosure SKILL.md was 365 lines, loaded in full on every add-on task. Split it per Anthropic's Agent Skills best practices: keep steps, completion criteria, and the mechanism ladder inline; push rationale, war-story examples, and Codex CLI invocation details into reference files loaded only when that branch is taken. - SKILL.md: 365 -> 171 lines. The "ship the simplest solution" rule was stated three times; now once. Steps 3/6/9 keep their load-bearing checklist but point to detail files instead of inlining it. - references/evidence.md (new): measurement methodology, the host-generalization failure examples, the merged-and-inert case studies - references/codex-review.md (new): CLI invocation, prompt guidance, plan-attack checklist - references/simplify.md (new): mechanism-ladder case studies Also replaces the old "Token efficiency" section (which named this maintainer's personal MCP tools - rtk/headroom/tokensave - not guaranteed present for CI agents or other collaborators using the checked-in copy) with a subagent-delegation instruction: Codex's plan/code review and PR-comment triage on >5 threads should run in a subagent that returns a condensed summary, not raw output, into the calling session. * fix(skill): address PR review feedback - SKILL.md: define $SKILL once and state that all scripts/ and references/ shorthand paths are relative to it — they read as repo-root-relative otherwise and don't resolve from an add-on directory - codex-review.md: drop the reference to a "global CLAUDE.md note" that isn't in this repo's CLAUDE.md; describe --sandbox read-only accurately (reads allowed, writes/exec blocked, approvals disabled) instead of "cannot run anything"; add the missing & so the example is actually backgrounded as the prose claims - evidence.md: use smaps_rollup for process RSS — plain smaps prints one Rss: line per mapping (47 for a trivial process here), not a total - simplify.md: drop the absolute "removals cannot regress" claim, which contradicted the /dev/shm case study in evidence.md * refactor(skill): apply independent quality-review findings From an independent model review of the skill against the Agent Skills best-practice guides: - traps.md: CHANGELOG was described as "the only hard gate", contradicting SKILL.md — the HA add-on linter and the image build also block PRs (verified against onpr_check-pr.yaml). Gates list corrected. - codex-review.md: the "attack your own plan" checklist is run by the main agent, but lived in the file whose stated consumer is the delegated subagent — an agent that delegates correctly would never see it. Moved inline into SKILL.md step 3. - SKILL.md: delegation instruction now says exactly what to do (spawn a subagent whose prompt includes references/codex-review.md and follows its invocation) instead of "delegated per the rule above". - SKILL.md: traps.md is no longer mandatory reading on the light path — the light-path facts it holds (versioning, CHANGELOG format) are inline in step 7; it stays required when touching scripts/Dockerfiles/env. - SKILL.md: dropped the bundled-files table (every row already cited at point of use) and the "read the script when you use it" anti-instruction — scripts are run, not read. 177 -> 167 lines. - description: 982 -> 550 chars; removed workflow narrative that does nothing for skill selection and the stale-prone model name, kept all trigger terms. * fix(skill): note that CI hard gates skip on non-addon PRs The three hard gates in onpr_check-pr.yaml (changelog check, addon-linter, check-build) are each matrixed over check-addon-changes.outputs.changedAddons and if:-skipped when it is '[]'. A PR touching only docs, .github/ or .claude/ therefore shows them as "skipping" rather than passing — which should not be read as a green build. Verified against onpr_check-pr.yaml lines 64, 83, 101 and against this PR's own check output.
2.4 KiB
Codex review — invocation and prompt guidance
Used for step 3 (plan review) and step 6 (code review), full loop only. Codex is a genuinely different model reading the files itself; on this workload it has repeatedly been worth the minutes. Delegate the invocation to a subagent (see SKILL.md's subagent-delegation note) so its output doesn't land verbatim in your context — have the subagent return only Codex's objections and your assessment of each.
Invocation
Use the CLI, not the MCP tool, for prompts of this size. The codex MCP tool timed out twice
on ~4 KB prompts (2026-08-03); the CLI with the same content succeeded. The MCP tool is still fine
for short questions.
--sandbox read-only lets Codex read files but blocks writes and command execution, and
approval_policy=never means it will not be prompted for permission to run anything either — so
paste every number into the prompt rather than expecting Codex to gather it. - < feeds the
prompt file on stdin. Run it in the background so you are not blocked for the several minutes it
takes (& here, or your harness's background-task mechanism):
codex exec --model gpt-5.6-sol --sandbox read-only --skip-git-repo-check \
-c approval_policy='"never"' - < prompt.md > codex_out.txt 2>&1 &
Writing the prompt
- Plan review (step 3): include the files to read, your measurements with numbers, the proposed changes, and explicit instructions to challenge you. Ask direct questions ("is this really add-on-fixable?", "give the precise flag set") rather than "review this".
- Code review (step 6): point it at
git diff origin/master...HEADplus the reasoning behind each hunk. Ask specifically what breaks: upgrade paths, hosts unlike this one, users who configured things by hand. Ask directly whether a simpler mechanism would achieve the same thing — an outside reader spots one-level-too-deep framing far more easily than the person who just built it. - Codex's sandbox often cannot run local commands and falls back to reading GitHub, so paste the evidence in rather than assuming it will find it.
Codex agrees with confident premises. It has confirmed a wrong conclusion stated too confidently, and separately caught a genuine methodology error in the same review. Treat its confirmations with the same scepticism as its objections — especially about the build.