The trust-boundary list names only remote channels, so local values that the
OS hands you — another process's command line or environment, a filename on a
shared volume, a path in a job payload — read as internal. The one rule about
destructive actions (LLM06) governs who may act, not what gets hit: a
confirmed call with a wrongly derived target deletes the root just the same.
A shape check ("absolute, at least one directory deep") proves well-formedness
and gets mistaken for authorization.
SKILL.md gets the extended trust-boundary item, a prose-only "Destructive
Operations on Derived Paths" next to File Upload Safety, and one line each in
the Input checklist, Red Flags and Verification. The worked example lives in
references/security-checklist.md, per skill-anatomy's rule to move detailed
material out of SKILL.md — the file is already over the 500-line budget, so
this keeps the per-activation cost to +11 lines.
Two limits are stated where the snippet is copied from, rather than implied
away: a marker inside the tree is self-attestation until its integrity is
protected and the expected owner comes from authenticated state, and
resolving a path and then operating on the name is a check/use race wherever
an untrusted process can swap an ancestor.
No new directory, frontmatter unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A correlation ID identifies a run, not the code path that started it. When a
scheduler, a replay endpoint and a manual CLI run all reach the same job and
write into one sink, the lines are interchangeable — attributing one falls
back to elimination against external records (scheduler history, process
table, deploy log) that only happen to still exist.
Adds a paragraph plus a short example to "3. Structured logging" — stamp the
entry point where the run starts, next to the correlation ID, and propagate
both across queue metadata and outbound calls — and one line each to Red
Flags, Verification, and references/observability-checklist.md.
The field is `entryPoint` rather than `source`: Elastic Common Schema reserves
`source.*` for network fields (source.ip, source.port, …), so a scalar
`source` collides with that mapping and can get documents rejected.
No new heading, no new directory, frontmatter unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two skills carry core body content whose vocabulary never reached their
descriptions, so Tier-2 trigger routing cannot see it:
- deprecation-and-migration: Expand/Contract database schema migrations
(added in #345) - description now mentions database schema migration,
renaming/dropping a column, expand/contract.
- security-and-hardening: dependency-audit triage and supply-chain hygiene
(hardened in #392, delegated to by code-review-and-quality) - description
now mentions dependency audits, audit-finding triage, supply-chain risk.
Adds four positive trigger cases so the suite can see these gaps.
Measured: baseline 86% (72/84); cases-only 82% (4 hard misses, 'shares no
vocabulary'); cases+fix 86% (76/88), 140 checks, 0 errors, no existing case
loses rank 1.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Affected agy 1.1.x releases report the 8 legacy command TOMLs as
converted to skills, but the converted wrappers never appear in the
slash-command or skill catalog — plugin validate passing confirms the
files are well formed, not that /build and the other wrappers exist.
Replace the slash-command table with a wrapper-to-direct-invocation
map (/agent-skills:<skill-name>, /agents for the webperf persona),
note the wrapper-only behaviors that are unavailable (/build auto
orchestration, /ship persona fan-out), warn against the YAML
frontmatter workaround that breaks Gemini CLI's TOML parser, and add
a post-install verification step. Align the README blurb with the
same guidance.
Federico's review on #472 noted the floor is the one thing with no de facto
tool, so agents reinvent a check-floor each run. Add references/floor-guard.md
(the Step 6 checks as a diff-scoped reference implementation, exit 0/1/2, with
patterns adaptable per ecosystem) and point Step 6 and the escalation path at
it. Also mark CONSTRAINTS.md as the canonical source of commands over the
package.json wrappers, and document a floor-only first run plus a CI-only
option for machine-wide security tools.
When /plan runs for new work while tasks/plan.md and tasks/todo.md
still hold unchecked tasks, the agent silently replaces them,
destroying the in-flight plan's state (reported in #518).
Add a convention-neutral guard: replanning the same work updates in
place; different work stops and asks the user before touching the
existing files. Mirror the rule for external task list targets (no
bulk-closing another plan's items), and add matching Rationalization,
Red Flag, and Verification entries plus the guard line in the /plan
command.
Deliberately does not introduce a parallel-lane layout — that
convention decision is being held open in #518; this fixes only the
data-loss half.
Review feedback from @federicobartoli on #316.
allowed-tools was described as restricting the tool set. Per the Claude
Code docs it is a permission pre-approval: listed tools run without a
prompt for the turn that invokes the skill, the grant clears on the next
message, and nothing leaves the tool pool.
disallowed-tools is the field that actually restricts, so it now carries
the least-privilege guidance. Added the portability caveat that it is a
Claude Code field rather than one of the specification's six, so it fails
packaging if placed in a published SKILL.md.
Claude-Session: https://claude.ai/code/session_01TuWNaEV9RFXpTxqeBRTRg8
Link the Agent Skills spec, document the optional `agent` companion to
`context: fork`, clarify that commands and skills share frontmatter, and
add #35 to the consolidated Status list.
Address review feedback on #316:
- State explicitly that this supersedes the inline top-level frontmatter approach, so kind/model/temperature/max_turns/tools/context must not appear at the top level of a skill.
- Add a copy-pasteable .gemini/agents/*.md example using thinking_level instead of hardcoded temperature for Gemini 3.x.
- Update Status: #272 and #36 are closed in favor of this approach.
Add a draft reference for per-agent runtime configuration that keeps shared SKILL.md files portable while documenting the vendor-specific controls each agent offers (Claude Code, Gemini CLI, Antigravity) as an opt-in.
Review feedback from @federicobartoli on #521.
The low-selectivity rows read as if indexing a skewed column never
helps. That holds only when querying the dominant value; filtering on
the rare value is exactly the case a partial index serves. Scoped both
the SKILL.md table row and the checklist item.
loadOnce referenced an undeclared Row type. Made it generic so it
typechecks when pasted as-is.
Claude-Session: https://claude.ai/code/session_01TuWNaEV9RFXpTxqeBRTRg8
#358 broadened the performance-optimization description to cover
"frontend, backend, queries, and databases", but the body's backend
coverage was a single N+1 example, against the full Core Web Vitals
and art-direction treatment on the frontend side. Routing a "slow
query" or "connection pool" prompt here landed on a snippet.
Adds three measure-first patterns inline, each with a "when NOT to":
- Query plans: read EXPLAIN ANALYZE before indexing; composite column
order (equality first, then range/sort); the four cases where an
index does not help; revert an index that did not change the plan.
- Connection pool exhaustion: the distinctive symptom, one pool per
process, why a bigger pool relocates the queue instead of removing
it, and the proxy answer for serverless.
- Caching: layer choice (in-process, shared, edge), key design as a
correctness concern, one invalidation strategy rather than an
accidental mix, and stampede protection.
Deeper material goes to references/performance-checklist.md to keep
SKILL.md readable: read/write patterns, negative caching, request
coalescing, and query-plan, index, pooling and cache checklists.
Closes#378
Claude-Session: https://claude.ai/code/session_01TuWNaEV9RFXpTxqeBRTRg8
The persona used Critical/Important/Suggestion while code-review-and-quality
uses Critical/Required/Optional/Nit, so the same finding got labeled differently
depending on which entry point ran the review. Align the persona to the skill's
four-level scheme (the skill is the source of truth) and note the shared
vocabulary to prevent future drift.
Rewrite docs/opencode-setup.md so it no longer instructs users to copy
the repo-scoped root AGENTS.md. Instead, document how to install skills
into .opencode/skills/ (project), ~/.config/opencode/skills/ (global),
and cross-compatible Claude/agent paths. Provide a project-local
AGENTS.md template and keep the intent mapping and lifecycle guidance.
Update the README summary to match the new installation model.
Refs #99
Refs #119
The skill body already covers pull requests -- "ideally a separate PR" and
"Target ~100 lines per commit/PR" -- but the frontmatter description never
uses the words "pull request" or "PR". Prompts phrased that way therefore
do not route to this skill first.
Adds a trigger case for the gap, and the vocabulary that closes it.
Tier-2 routing, via scripts/run-evals.js:
baseline 86% 67/78
with new case, no fix 85% 67/79 <- case does not rank first
with new case and fix 86% 68/79 <- case ranks first
Exactly one case changed rank; no other skill regressed.
scripts/validate-skills.js passes: 24 skills, 0 errors, 0 warnings.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`dirName in SECTION_EXEMPT_SKILLS` walks the prototype chain, and
`constructor` satisfies KEBAB_CASE (the `*` quantifier permits a single
word). A skill directory named `constructor` therefore resolved to
Object.prototype.constructor and was silently exempt from every
required-section check — `exempt: true`, zero errors, no sections. The
bypass guard missed it for the same reason, since the resolved value is
truthy.
Both lookups now use Object.hasOwn, which is what the comment above the
allowlist already promises: "Exemptions live HERE, not in skill
frontmatter, so contributors cannot bypass the validator by editing their
own skill file."
Adds scripts/lib/skill-lint-test.js — skill-lint.js was the only
validator without a test file. Confirmed the prototype-chain test goes red
against main; the other six pass either way, so existing behaviour is
unchanged.
Scope kept to the exemption lookup: #428 already rewrites frontmatter
parsing and the cross-reference patterns, so this stays clear of both.
Reworked from a standalone skill into an addition to api-and-interface-design,
per review feedback on #479.
#241 covers the contract surface: which methods are idempotent, accepting an
Idempotency-Key header, replaying the stored result. This picks up where that
stops -- what the server has to do so the guarantee actually holds:
* derive the key from the intent, not the attempt, with the patterns that
look right and are not (randomUUID per call, timestamps, user+amount)
* claim atomically; a SELECT then an INSERT is a race, and the unique
constraint is the mechanism
* guard the payload, so a reused key with a different body fails loudly
instead of replaying the wrong response
* decide deliberately what an in-flight duplicate receives -- 409, wait, or
202 -- rather than accepting whatever falls out of the control flow
* treat unknown as a third outcome distinct from failure, and record intent
before calling out so a crash leaves evidence
* set key retention from the longest re-delivery path, including DLQ replay
Adds three rationalizations, four red flags and five verification items so the
guidance is enforceable rather than advisory.
Validators: validate-skills 24 skills 0 errors 0 warnings,
validate-reference-links 0 errors, run-evals --min-rank1 80 -> 124 checks,
0 errors, rank-1 86%.
The task list destination was hardcoded as tasks/todo.md in five places
across planning-and-task-breakdown, plus once more in
spec-driven-development's Phase 2 output convention. Projects tracking
tasks in an external tracker (bd/beads, Jira, Linear, GitHub Issues) had
to hand-edit every reference in a local fork.
Define the target once in a Task List Target section: default remains
the tasks/todo.md markdown checklist (downstream /build behavior is
unchanged), and projects can designate an external tracker via their
agent rules. All other references now defer to that single definition,
and spec-driven-development points at it instead of restating the path.
The setup doc claimed plugins install to ~/.gemini/antigravity-cli/plugins/
but on current agy releases they land in ~/.gemini/config/plugins/. Issue
#445 reporter confirmed the plugin lives under config/ on disk. Update the
path and add a note so users check the right location first.
Signed-off-by: Yunare Maia <yunare@gmail.com>
Implements the v1 scope agreed in #431: when one requirement bundles
several independently testable capabilities, spec-driven-development now
runs a bounded front-step before Specify — detect multi-capability scope,
propose a capability map (stable module ids, one-way dependency direction,
build order), gate it on human approval, then recurse the gated workflow
per module in dependency order.
Kept deliberately small per the maintainer's scoping:
- detection + module map + stable identity only; no per-module artifact
tree — module specs reuse the root-level SPEC-<id>.md naming so the
layout follows the delta-spec direction in #383 rather than leading it
- the simple path is preserved: single-capability requests skip Phase 0
entirely, and the section says so first
- non-goals held: no PM framework, no forced hierarchy on small features
Also:
- description gains the decomposition vocabulary so realistic asks route
here (both new positive triggers rank #1)
- /spec command wrappers (.claude, commands/, .gemini) gain one matching
step, kept in parity
- eval case: +2 positive triggers, +1 owner-negative guarding the
planning-and-task-breakdown boundary, +1 execution eval backed by a new
multi-capability fixture (portal-brief.md)
Verification: validate-skills 24/24, validate-commands 8/8, run-evals
127 checks 0 errors 0 warnings, rank-1 86% (67/78) over floor 80,
behavioral dry-run resolves both spec evals.
The session-start hook emitted {"priority", "message"} JSON on all three
of its output paths. Codex CLI validates SessionStart hook output and
fails the hook on that shape ('hook returned invalid session start JSON
output', #465); the documented contract for both Codex and Claude Code is
{"hookSpecificOutput": {"hookEventName": "SessionStart",
"additionalContext": "..."}}
Switch all three paths (meta-skill injection, jq-missing fallback,
meta-skill-missing fallback) to that envelope. Verified each path emits
valid JSON of the new shape: happy path via jq shape assertion, jq-missing
via PATH='' run, meta-skill-missing via a copy outside the repo.
Picking 'accessibility' returned a threshold and no mechanism, so the
agent had to invent the setup and two agents would invent two different
ones. That is the non-determinism the skill exists to remove.
Adds a table mapping every dimension to the de facto tool, its install
command, its run command, and what to gate on, across JS and Python. De
facto matters here: these rule formats are what the ecosystem targets, so
a team's existing config keeps working.
Five failure modes called out. gitleaks needs --redact or the matched
secret lands in the agent transcript. axe and Lighthouse need a running
URL, and a project without one should drop the dimension rather than fake
a check. Stryker and Semgrep scope to the diff or nobody runs them twice.
Coverage reads the lcov the suite already wrote.
CONSTRAINTS.md now carries the command next to each rule, so a dimension
with a number and no command reads as the aspiration it is.
Addy Osmani