Plugin subagents sit at the bottom of Claude Code's scope priority table,
so a code-reviewer (or security-auditor / test-engineer) defined in
.claude/agents/ or ~/.claude/agents/ silently wins over the plugin's
version when /ship spawns personas. This is intentional — user
customization should take precedence — but the override is silent, so
without documenting it people will waste time wondering why /ship isn't
using the persona they expected.
Adds a one-liner to Phase A framing this as a feature. Suggested in
review.
The previous rule — 'if the change is small enough that fan-out adds more
overhead than value (e.g. a single typo fix)' — left too much room for
subjective interpretation. A 10-line change to auth code is risky
regardless of line count; a 500-line test-file rename is not.
New rule combines size thresholds (2 files, 50 lines) with a
sensitive-path carve-out (auth, payments, data access, config/env). All
conditions must be true to skip; any one makes fan-out the default.
Suggested in review.
The previous text implied personas behave identically as subagents and
teammates. Per the Agent Teams docs, the skills and mcpServers
frontmatter fields in a subagent definition are not applied when the
definition runs as a teammate — teammates load those from project and
user settings instead.
Adds a qualifier so persona authors don't assume a skills: [...] block
will load in both modes. Flagged in review.
Per the Agent Teams docs, a persona body is appended to the teammate's
system prompt as additional instructions — not a replacement. The prior
wording implied the persona owned the whole prompt, which would mislead
a persona author about what coordination instructions they inherit from
the lead (SendMessage, task-list tools, etc.).
Fixes the same inaccuracy in two locations (agents/README.md and
references/orchestration-patterns.md). Flagged in review.
Walk through a realistic scenario (intermittent 30-second checkout hang
with four plausible root causes) where Agent Teams beats /ship's subagent
fan-out: teammates can challenge each other's hypotheses directly via
inter-teammate messaging, which subagents cannot do.
Includes the one-time CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 setup, a
copy-paste trigger prompt that reuses the existing personas as teammate
types, an explicit anti-pattern warning against wrapping the workflow as
a /debug slash command (which would lose the inter-teammate messaging),
and a 'when not to use Agent Teams' decision rule.
Verify the orchestration design against the official Claude Code docs and
make the platform mapping explicit:
- /ship now names the Agent tool and the subagent_type field directly,
with a fallback note for harnesses that lack an Agent tool.
- AGENTS.md notes that personas work as both subagents and Agent Teams
teammates, and lists the unsupported plugin frontmatter fields.
- agents/README.md gains a Claude Code interop section and notes that
rule #2 is also a hard platform constraint.
- references/orchestration-patterns.md gains a Claude Code compatibility
appendix covering plugin paths, the subagents-vs-teams comparison, the
built-in Explore/Plan/general-purpose subagents, and the parallel
Agent tool call requirement. Pattern 5 now points at Explore first.
No behavior changes; documentation only.
Catalog the five endorsed patterns (direct invocation, single-persona
slash command, parallel fan-out with merge, user-driven sequential
pipeline, research isolation) and four anti-patterns (router persona,
persona-calls-persona, sequential paraphrasing orchestrator, deep
persona trees). Includes a decision flow and a gate for when to add
new patterns to the catalog.
Each persona now ends with a three-bullet block stating when to invoke it
directly, which slash commands wrap it, and the rule that personas do not
invoke other personas. Keeps the persona honest about its place in the
workflow without re-stating the broader orchestration model.
Replace the linear pre-launch checklist with a three-phase orchestrator:
Phase A spawns code-reviewer, security-auditor, and test-engineer in
parallel; Phase B merges their reports in the main context; Phase C
produces a go/no-go decision with a mandatory rollback plan.
This is the canonical example of valid multi-persona orchestration in the
repo. Trivial edits should still skip fan-out per the rules block.
Document the three composable layers (skills, personas, slash commands),
the rule that personas do not invoke other personas, and that parallel
fan-out via /ship is the only multi-persona pattern this repo endorses.
Points contributors at agents/README.md and references/orchestration-patterns.md
for the full guidance.
New agents/README.md introduces the three-layer model (skill / persona /
command), a decision matrix for picking the right invocation style, and
worked examples of both valid (parallel fan-out via /ship) and invalid
(router persona) orchestration. Establishes the rule that personas do not
invoke other personas.
Add an INP-specific measurement workflow covering field data via CrUX Vis,
DevTools interaction tracing, and mid-range Android device testing. Extend
the web-vitals snippet with the attribution build to surface inputDelay,
processingDuration, and presentationDelay. Add a checklist item for
deferring non-critical work out of event handlers to avoid delaying
interaction response.
Drop the 24h TTL: HTTP validators are the whole freshness contract.
Key cache on URL alone; prompt-aware keying with normalization gave
false safety (semantic differences slipped through). Prompt is kept
as metadata and surfaced in the hit message so the next agent can
judge whether the earlier reading applies. Reframe docs around
"HTTP resource cache, not prompt cache".
While here, fix two latent bugs:
- Replace the unquoted heredoc in the pre-hook with printf. The
heredoc expanded $vars and backticks inside cached content, so a
compromised doc page could trigger command substitution on cache
hit.
- Strip CR before awk paragraph-mode parsing of curl -I -L output
so blank separators between response blocks on a redirect chain
are recognised (was silently picking intermediate headers).
Remove dead -v IGNORECASE=1 (gawk-only; tolower() already handles it).
The maintainer confirmed the original preventDefault fix was mergeable, but also pointed out that the example could better mirror native button behavior. This follow-up keeps the docs-only scope while making the example clearer: Enter stays on keydown, Space only suppresses default scrolling on keydown, and activation happens on keyup.
Constraint: Keep the change limited to the existing accessibility example in the frontend UI skill
Rejected: Leave the first patch as-is and wait | low-cost maintainer suggestion that improves behavioral fidelity
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: For custom role=button examples, document Space activation in a way that does not reintroduce page scrolling or drift from native button timing without explanation
Tested: git diff --check; manual browser/WKWebView reasoning against the example semantics
Not-tested: Cross-browser live rerun after the keyup refinement
Adds a pair of optional Claude Code hooks that cache WebFetch output
on disk but revalidate every reuse against the origin. Content is
served only when the server returns 304 Not Modified, so
source-driven-development's "verify against current docs" guarantee
still holds across sessions.
- hooks/sdd-cache-pre.sh: PreToolUse hook. For a cached entry, issues
a HEAD with If-None-Match / If-Modified-Since. On 304, blocks the
WebFetch (exit 2) and returns cached content via stderr; otherwise
allows the fetch through.
- hooks/sdd-cache-post.sh: PostToolUse hook. Captures response plus
current ETag / Last-Modified. Entries without a validator are
never stored — without one, the pre hook cannot verify freshness
and caching would amount to trusting memory.
- Cache key: sha256(url + normalized_prompt). Prompt is lowercased
and whitespace-collapsed so stylistic variants hit the same entry;
semantically different prompts still miss.
- Hard 24h TTL as a safety net against misbehaving origins.
- hooks/SDD-CACHE.md: opt-in setup, end-to-end testing, debugging.
- .gitignore: ignore the .claude/sdd-cache/ directory.
Hooks are opt-in: users register them in .claude/settings.json. The
source-driven-development skill itself is unchanged.
The frontend accessibility skill is meant to model production-grade,
WCAG-aligned UI guidance. The existing custom button example activates
on Space, but it also leaves the browser's default Space scroll in
place on a non-native button. This update keeps the example small while
making the keyboard behavior accurate.
Constraint: Keep the PR docs-only and scoped to the validated example
Rejected: Add more explanatory prose around custom button semantics | wider docs change than needed for a one-line guidance fix
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep this example aligned with actual browser behavior for non-native buttons; avoid simplifying away required keyboard handling details
Tested: Local WKWebView/browser reproduction; git diff --check
Not-tested: Other browsers beyond the local WebKit-based reproduction
Related: #78
Clarified the requirement for the skip-to-content link to be visible on keyboard focus - as it is mostly beneficial to users that can see the screen (but also others)
- Reframe 'When NOT to use' around version-dependent correctness
- Add guidance for conflicting official sources
- Prefer deep links with anchors in citation examples and rules
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.
- Add width/height to <source> elements for correct aspect-ratio in art direction.
- Use realistic 'sizes' attributes in hero image examples.
- Remove 'decoding=sync' from hero images to avoid blocking the main thread.
- Align TTFB 'good' threshold with web.dev standards (800ms).
- Distinguish synthetic (Lighthouse) vs RUM (web-vitals) measurement approaches,
clarifying when each is appropriate: synthetic for CI regression detection,
RUM to validate real user impact.
- Expand TTFB diagnosis from a single vague hint into a decision tree that breaks
down each component (DNS, TCP/TLS, server processing) with specific next steps.
Mirrors the tree in the skill and adds a dedicated checklist section.
- Fix image optimization example: the previous "GOOD" example applied loading="lazy"
without distinguishing the LCP hero image from below-the-fold images. Hero images
must never be lazy-loaded. New example separates both cases explicitly.
- Add art direction + resolution switching to the hero image example using <picture>
with media queries for mobile/desktop crops and srcset for density variants.
Mobile-first: <img src> fallback points to the mobile version.
Covers AVIF → WebP → JPG format cascade and fetchpriority="high" for LCP.
- Correct the date-fns tree-shaking example: modern bundlers (Vite, webpack 5+)
handle named imports automatically. The "BAD" pattern was not actually bad,
and following it could lead to unnecessary micro-optimizations. Real gains
come from dynamic imports and route-level code splitting, which the example
now illustrates instead.
Addy Osmani