mirror of
https://github.com/alexbelgium/hassio-addons.git
synced 2026-08-23 21:33:32 +02:00
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.
42 lines
2.4 KiB
Markdown
42 lines
2.4 KiB
Markdown
# 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):
|
|
|
|
```bash
|
|
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...HEAD` plus 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.
|