Resolve README.md Reference Checklists table conflict by keeping both new
rows: observability-checklist (this PR) and orchestration-patterns (#290,
already on main).
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.
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
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.
- README: remove "(Recommended)" from the Antigravity CLI install section
(Claude Code already carries that badge); bump the commands/ count to 8.
- Add commands/webperf.toml so Antigravity users get the /webperf
web-performance-auditor command at parity with Claude and Gemini.
Follow-up after the #222 merge left the new persona/command only half-wired:
- Register web-performance-auditor in the README agents table, the
getting-started "Using Agents" table, and CLAUDE.md (3 -> 4 personas).
- Document /webperf in CLAUDE.md and the getting-started command table.
- Add .gemini/commands/webperf.toml so Gemini users get /webperf too
(mirrors the Claude command; persona invoked inline rather than spawned).
Fills the gap between debugging-and-error-recovery (dev-time) and
shipping-and-launch (launch-day monitoring): how to instrument code
as it's built so production behavior is visible and diagnosable.
Covers structured logging with correlation IDs, RED/USE metrics with
cardinality guidance, OpenTelemetry tracing, and symptom-based
alerting with runbooks. Follows the standard skill anatomy (Overview,
When to Use, Process, Rationalizations, Red Flags, Verification).
Registered in README tables/structure, CLAUDE.md phases, and the
using-agent-skills discovery tree (hooks/session-start-test.sh passes).
Per review feedback on #220:
- Drop the `fast` alias (implied skipping verification); keep `auto`
(canonical) and `all`, and state explicitly that autonomous mode is not
faster per task — it only removes human stepping between tasks.
- Tighten spec detection to a closed set of paths (SPEC.md at root,
docs/SPEC.md, or spec/*.md) instead of "SPEC.md (or equivalent)", so a
stray README can't be treated as a spec.
- Define approval as an unambiguous affirmative; hedged responses are not
approval.
- Add resume contract: re-invoke /build auto to pick up the next task.
- Add a high-risk catch-all: anything you can't undo with `git revert`.
- Add dependency fallback: execute in declared plan order when deps aren't
explicit.
Mirrored across the Claude and Gemini commands.
Adds an autonomous mode to the build command: once a spec exists,
`/build auto` (also `all`/`fast`) generates the plan if missing, takes a
single plan approval, then implements every task in dependency order with
full TDD and a commit per task.
Removes the manual stepping between tasks without removing verification —
each task still earns a passing test and its own commit, so any point is a
clean rollback. Auto-pauses for human input on failures, spec ambiguity,
or high-risk/irreversible tasks (auth, destructive migrations, payments,
deletes, deploys, secrets).
- .claude/commands/build.md: two-mode definition (default vs auto)
- .gemini/commands/build.toml: mirrored for Gemini CLI
- README.md, docs/getting-started.md: document the new mode
Adds interview-me, a skill that sits upstream of every other
Define-phase skill. Trigger: an underspecified ask, or the user
explicitly invoking the skill ("interview me", "are we sure?",
"stress-test my thinking").
The gap it fills: idea-refine generates variations from a raw idea,
spec-driven-development writes requirements down once you know them,
and doubt-driven-development stress-tests a plan after you've drafted
one. None of those cover the moment before — when the user has said
"build me X" and X is the conventional answer rather than what they
actually want. This skill is the structured interview that surfaces
the gap before any plan, spec, or code exists.
Distinctive mechanics:
- Confidence numbers as forcing function (Step 1 commits to 0-100%)
- Q + GUESS format: every question carries the agent's hypothesis
- One question at a time, never batched
- Checkable stop condition: "Can I predict the user's reaction to the
next three questions I would ask?"
- Six-line restate template ending in explicit yes
- Names the four bad yeses ("whatever you think", "sounds good",
"sure let's go", silence) with specific re-prompts
Registers the skill in:
- CLAUDE.md (Define phase, also adding idea-refine which was missing)
- README.md (skills table, count, project tree)
- skills/using-agent-skills/SKILL.md (flowchart, lifecycle sequence,
quick reference table)
Resolves README.md conflict by taking main's wording ("entry points.
The pack includes 21 skills total") and Meta section, both landed in
PR #142 while this PR was open. The doubt-driven-development row in
the Build table and the directory tree entry auto-merged cleanly.
Folds in the safety and consistency findings surfaced by running
the skill against itself in two cycles (single-model adversarial
review + cross-model verification via Codex).
Cross-model escalation is now offered in every interactive cycle,
and the CLI invocation path uses a read-only sandbox with prompts
piped through stdin to neutralize shell-escaping and prompt-injection
risks (verified against Codex 0.128.0 and Gemini 0.41.2 locally).
Internal consistency fixes from the adversarial self-review: the
adversarial prompt explicitly overrides persona templates; the
persona roster is referenced rather than duplicated; the Step 2
'Claim' bullet is renamed Assertion to disambiguate from the Step 1
CLAIM block; the manual fallback in Loading Constraints is labeled
as a degraded last-resort path; the forward reference to Step 3 is
anchored; the Verification checklist no longer contains an item not
derivable from the Process; and using-agent-skills's Lifecycle
Sequence now includes the skill at position 7.
Codifies adversarial fresh-context review as an in-flight development
posture, distinct from /review (post-hoc PR-level verdict). Every
non-trivial decision passes through a 5-step cycle (CLAIM → EXTRACT →
DOUBT → RECONCILE → STOP) before standing.
Cross-model escalation is described as a contract, not as hardcoded
CLI invocations — the skill instructs the agent to ask the user which
external tool to use and how, since CLI syntax (Gemini, Codex, etc.)
changes and varies by environment.
Updates README skill listing (count, Build table, project tree),
CLAUDE.md Skills by Phase, and using-agent-skills flowchart + Quick
Reference for discoverability parity with the existing skills.
Introduces .gemini/commands/ with TOML definitions for 7 slash commands
(build, spec, planning, review, test, ship, code-simplify), enabling
Gemini CLI to auto-discover them from the project root.
The planning command is named /planning rather than /plan to avoid
conflicting with a Gemini CLI internal command name.
Updates README.md project structure tree and adds a Slash Commands
section with a reference table to docs/gemini-cli-setup.md.
Grounds every framework-specific implementation decision in official
documentation — verify, cite sources, and surface what's unverified.
Covers the full process from stack detection to citation format,
with a framework-agnostic design and optional documentation cache.
Moved test-driven-development from Verify to Build in both CLAUDE.md and README.md (table + directory tree). This reflects the feedback that tests should ship with each commit as part of the build phase, not as a separate verification step after the fact.
The `/install github:addyosmani/agent-skills` syntax throws
"Args from unknown skill" errors. Revert to the previous
two-step plugin marketplace commands that work correctly.
Fixes#11
Addy Osmani