The file-size paragraph used "1000 total lines" adjacent to the "~1000
lines changed" diff threshold, which let readers conflate "diff too
large" with "file too large". Spell out the distinction inline and
reframe total file length as an inspection signal rather than a hard cap.
Addresses @federicobartoli's review feedback on #304.
Per review: the paragraph said both "Required-by-default" and "flag and
suggest by default", which are opposite stances. Collapse to a single
stance — propose the simpler design for each signal, escalate to Required
only when the change actively makes structure worse.
Our five-axis review is broad but treats structural maintainability passively
("could this be fewer lines?"). This adds the depth a great reviewer brings to
structure, folded into the existing axes/process rather than a separate mode:
- Architecture axis: "reduce, don't relocate" (does the refactor delete
complexity or just move it?), canonical-layer/helper-reuse discipline, and
explicit type-boundary checks.
- Readability axis: treat new conditionals bolted onto unrelated flows and
repeated same-shape conditionals as missing-abstraction signals, not nits.
- New "Structural Remedies" section: name the restructuring move, not just the
problem (typed dispatcher, collapse duplicate branches, separate orchestration
from logic, reuse canonical helper, etc.).
- Change Sizing: gate total file size, not just diff size (~1000-line smell).
- Step 4: "lead with what matters" finding-prioritization rule.
- Verification: presumptive blockers, calibrated to our approval philosophy
(surface and propose the simpler design; block only when structure gets worse).
- Matching Common Rationalizations and Red Flags.
Purely additive; validator passes (24 skills, 0 errors).
The "Categorize Findings" table defines Critical, Required (no prefix),
Optional/Consider, Nit, and FYI. Two other spots used labels outside that
set: the Multi-Model Review prompt said "Critical, Important, or Suggestion"
and the Verification checklist referenced "All Important issues". "Important"
and "Suggestion" are never defined, so an agent following the skill can't map
them to a severity. Align both to the taxonomy.
Add a "Before proposing a new skill" subsection to CONTRIBUTING.md that
defines a checklist contributors run before opening a new-skill PR: search
the existing catalog, check open PRs for overlapping proposals, confirm the
idea fits the skill anatomy, and justify in the PR description why it isn't
already covered.
The goal is to set clear rules/guidelines that curb duplication, since the
open-PR backlog has accumulated clusters of near-duplicate skill proposals.
Reorganize the section into "Before proposing a new skill" and "Creating the
skill" so the decision step comes before the how-to.
Per review feedback: clarify that cherry-picking individual skills works,
but running two frameworks as active routers at once causes command-name
conflicts, competing routing, and clashing TDD philosophies. Recommend
one primary router + à la carte borrowing.
Resolve README.md Reference Checklists table conflict by keeping both new
rows: observability-checklist (this PR) and orchestration-patterns (#290,
already on main).
The Stop-the-Line Rule and Triage Checklist each have exactly 6 steps
(1-6). "Steps 4-10" referenced steps that never existed — this was an
original error present since the file's first commit, not a leftover
from a previous 10-step structure. Correct the range to match the
actual 6-step content.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The references/ directory ships five files, but the Reference Checklists
table in the README listed only four — orchestration-patterns.md was
missing. It is a real reference (linked from AGENTS.md and the agents
docs as the full pattern catalog), so add it to the table for parity
with the other four entries.
Every other shell script in the repo is 100755 (all six hooks/*.sh),
but skills/idea-refine/scripts/idea-refine.sh was committed 100644.
It has a #!/bin/bash shebang and is invoked as a runnable helper from
its SKILL.md. AGENTS.md also documents scripts/ as 'Required:
executable scripts'. Set the exec bit for consistency.
The validate-skills job pinned actions/checkout@v4 while the other two
jobs in the same workflow (test-fresh-install, test-plugin-structure)
use @v6. Align all three on @v6 for consistency.
The antigravity code-simplify command instructed the agent to read
"CLAUDE.md or AGENTS.md", but per docs/antigravity-setup.md the
Antigravity CLI reads AGENTS.md for project conventions. The CLAUDE.md
reference is a leftover from the Claude command variant. Align it with
the other platform commands, where each reads its own conventions file
(.claude reads CLAUDE.md, .gemini reads GEMINI.md).
The slash-command reference table in docs/getting-started.md lists every
lifecycle command except /code-simplify, even though it is documented in
the README, has command files for all platforms (.claude/.gemini/commands),
and the table already includes the more specialized /webperf. Add the
missing row mapping /code-simplify to the code-simplification skill.
hooks/simplify-ignore-test.sh was committed with mode 100644 while its
sibling test script hooks/session-start-test.sh is 100755. Both share
the same #!/bin/bash shebang and live in the same directory; set the
exec bit for consistency.
Claude Code v2.1.140+ flags the repo-root commands/ folder as "ignored" in
/doctor, `claude plugin list`, and the /plugin detail view, because
.claude-plugin/plugin.json points `commands` at ./.claude/commands (outside the
default folder) while a root commands/ still exists for Antigravity CLI.
List both locations explicitly so the default folder is no longer "ignored".
Per the plugins reference, the array form keeps the default and adds the custom
dir; the command loader only registers .md files, so Antigravity's
commands/*.toml are silently skipped (no extra Claude commands) and the lint
clears. No behavior change for Claude, Antigravity, or any other tool.
- Support single-quoted TOML description strings (previously silently returned null)
- Wrap file reads in try/catch to produce actionable CI errors instead of raw stack traces
- Remove dead tomlStems variable; declare allTomlStems once and compute allCanonicalStems for an accurate command count in the summary
- Simplify description mismatch output to always show all three values, removing a redundant conditional branch
When users manually copy hooks to .claude/ instead of installing via plugin, ${CLAUDE_PLUGIN_ROOT} is not set and the SessionStart hook silently fails.
This adds a fallback to ${CLAUDE_PROJECT_DIR}/.claude/hooks/ so the hook works in both plugin and manual install modes. If neither path exists, it silently succeeds.
Tools that scan agents/*.md as custom agent definitions (e.g. GitHub Copilot CLI) parse every Markdown file in agents/ and require YAML frontmatter. agents/README.md was docs, not an agent, so it triggered "malformed custom agent" warnings on every session start.
Moving the docs to docs/agents.md keeps agents/ containing only real agent definitions. Updates internal links in the moved file, in the four persona files, AGENTS.md, and adds a pointer from the root README.
Fixes#258
The recommended config attached the agent to the user's running Chrome
via --autoConnect ('recommended for most users'), giving it every open
window of the default profile: logged-in email, banking, GitHub
sessions. Combined with a page containing injected instructions, the
agent effectively holds the user's authenticated browser. The skill's
own Security Boundaries section treats browser content as untrusted,
but profile isolation is the layer that bounds the damage when those
rules fail.
Changes:
- Recommended config now uses --isolated (temporary profile, wiped on
close); documents that the server's default is already a dedicated
profile separate from the user's browser
- --autoConnect described accurately (Chrome 144+, requires enabling
remote debugging) and demoted to the logged-in-state use case
- New 'Profile Isolation' subsection in Security Boundaries with
escalation rules: dedicated profile -> test-only profile -> real
profile only with unrelated tabs closed
- Red flag added for attaching to the daily profile for localhost tests
Follow-up suggested in #223 review: folds in the useful half of #61
(the observability checklist) as this skill's quick-reference
companion, mirroring the security-and-hardening / security-checklist
pairing.
Aligned with the merged skill's framing: on-call questions first,
RED/USE metrics, cardinality rules, symptom-based alerting with the
page/ticket two-severity rule, telemetry verification, and a
pre-launch gate. Linked from the skill's Verification section and
registered in the README references table and CLAUDE.md.
The .claude-plugin/plugin.json agents array still listed only 3 personas;
add web-performance-auditor so the manifest matches the agents/ directory
(now 4). Verified with `claude plugin validate .`.
Addy Osmani